Skip to main content
Use the sections below to troubleshoot common integration and generation questions.

Authentication and API keys

Go to the GENGEN Dashboard, open API Keys, and create a key. Keys are scoped to your workspace. Copy the complete secret immediately because it is shown only once.
All requests use this base URL:
Add an Authorization header to every request:
See Authentication for server-side examples and key-handling guidance.
  • Confirm the key has not been revoked in the API Keys area of the Dashboard.
  • Send the key as Authorization: Bearer <key>, not as a query parameter.
  • Confirm that the key has not expired.
  • Check that the workspace has enough available balance for the request.

Balance and billing

Open the Dashboard and view the Overview area. It shows the current wallet balance and recent transaction history.
The final price depends on the selected model and operation. Video price can also vary by resolution, duration, and whether the request includes video input.Consult Pricing for current customer prices. Only the final charged price is relevant to API users.
New billable requests are rejected. A task accepted while sufficient balance was available can continue to a terminal state. Top up the workspace wallet from the Dashboard before submitting another billable request.

Video generation

Submit a task with POST /contents/generations/tasks. The response contains an id. Poll GET /contents/generations/tasks/{id} until status is succeeded, failed, cancelled, or another documented terminal value.A polling interval of three to five seconds is a reasonable starting point.
Many tasks complete within one to three minutes. Higher resolutions, longer durations, and provider queues can increase that time. Poll the task status instead of imposing a short fixed timeout.
Common modes include:
  • text_to_video: generate from a text prompt.
  • image_first_frame: use an image as the starting frame.
  • image_first_last_frame: provide both starting and ending frames.
  • multimodal_reference: guide generation with reference images, videos, or audio.
  • video_modify: edit an existing video.
  • video_extend: extend an existing video.
Availability varies by model. See Create video generation task for the normalized request structure.
Seedance model capabilities vary. Depending on the model, resolutions can include 480p, 720p, 1080p, and 4k; durations and supported aspect ratios also differ.Check the selected model before sending the request. The Seedance 2.0 Fast variant, for example, does not support 1080p or 4k.
Continue polling at a moderate interval and allow for provider queues. If a task remains non-terminal for an unusually long time, save its public task ID and contact support before repeatedly resubmitting the same billable workload.
Send clips in assets.referenceAudios, then refer to the first as Audio 1, the second as Audio 2, and so on. Audio numbering starts at 1 independently of image and video numbering. Specify whether each clip guides voice, music, sound effects, or rhythm.Use WAV or MP3 files up to 15 MB each. Seedance 2.0 variants accept up to 3 clips, each 2–15 seconds and at most 15 seconds combined, alongside at least one reference image or video. Seedance 2.5 accepts up to 10 clips, each 2–30 seconds and at most 30 seconds combined, and supports audio-only references.See Seedance reference audio for the request example and single-clip compatibility field.
For Seedance 2.0-series and 2.5 models, reference audio has no separate audio-input fee and its duration does not add billable input-video seconds. Adding audio alone does not select video-input pricing. Final charges still use reported video token usage and the applicable model and resolution price; source/reference video inputs and the generated output duration can affect the charge. The generateAudio output setting does not change the unit price for these models.See Pricing and the reference-audio billing explanation.
Common causes include:
  • Prompt text involving restricted, sensitive, or protected content.
  • Reference media rejected during asset preparation or generation content checks.
  • Generated output rejected by provider post-generation checks.
Revise the prompt or source material and submit a new request. For face-containing media, see Generate videos with face assets.

Troubleshooting and errors

The public Seedance video task API automatically registers HTTPS reference media before generation. Send the URL in assets.referenceImages or assets.referenceVideos, then poll the returned video task ID. To prepare reusable assets yourself, create a Virtual Portrait group, add the media, wait for Active, and generate with its asset:// URI. See Generate videos with face assets for both methods and failure diagnostics.
Try these steps:
  • Explicitly request fully original background music that does not imitate copyrighted works.
  • Describe the music style, mood, and atmosphere—for example, calm, expressive, and emotionally resonant.
  • Revise the prompt and regenerate. Audio is created anew each time, so retrying the same prompt may also resolve the issue.
For a more reliable workaround:
  • Disable controls.generateAudio if you do not need background music.
  • Provide royalty-free audio that you are permitted to use as an Audio input. This avoids relying on newly generated music and its copyright checks.
Limits are applied at the workspace or provider level and can vary by model. If you need a higher limit, contact your GENGEN support representative with the model, expected request rate, and concurrency requirement.
  • Use exponential backoff with jitter.
  • Reduce concurrent in-flight requests.
  • Inspect the returned machine-readable error code to determine which limit was reached.
  • Do not retry in a tight loop.
  • Verify that the key is complete and has not been revoked.
  • Format the header as Authorization: Bearer <key>.
  • Make sure server code is loading the intended environment variable.
  • Do not send the key as a URL query parameter.
Save the full JSON response, HTTP status, request time, and public task ID if available. Do not include your API key in logs or support messages.See Errors for the standard error envelope and retry guidance.

Files and assets

Files uses a direct-upload token handshake. A supported Blob client uploads the media directly and returns a public file URL that can be used in generation requests.Asset Groups hold curated assets such as Virtual Portrait or verified real-person references. Use them when an API workflow requires an asset:// URI or when related assets should remain organized together.
Common supported formats include:
  • Images: JPEG, PNG, and WebP.
  • Videos: MP4 and MOV with supported codecs.
  • Seedance reference audio: MP3 or WAV, up to 15 MB per file. AAC and M4A are not supported for this input.
Exact size, duration, codec, and upload restrictions depend on the endpoint and model; successful file upload does not guarantee a model accepts that format. Check the relevant API reference before uploading large media, and see Seedance reference-audio limits.
For Seedance 2.0 or 2.5, send an HTTPS portrait URL to the public video task API and let GENGEN prepare the asset automatically. Alternatively, create an Asset Group and Asset yourself, wait for Active, and reuse the returned ID as asset://<ASSET_ID> in generation requests.Start with Generate videos with face assets.When the subject needs to provide explicit authorization, create a Real-Person Verification Session, direct the subject to the returned H5 URL, and then retrieve the verification result.
No. Poll Get asset and wait until Result.Status is Active. Preprocessing often completes quickly, but clients must use the returned status rather than assume readiness after a fixed delay.

Error reference

API errors include an HTTP status, stable error code, and optional structured context. Branch on the machine-readable error code instead of comparing message text. See Errors for response format, status categories, and retry guidance. Search the BytePlus error reference when the response includes a provider.byteplus_* error code.