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.
Common causes include:
  • Prompt text involving restricted, sensitive, or protected content.
  • A reference image or video with a recognizable face that was not prepared through the required Asset Group workflow.
  • 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

Add the material through the Virtual Portrait workflow, wait until the asset becomes Active, and generate with its asset:// URI. See Generate videos with face assets.
Disable controls.generateAudio, then submit the generation request again.
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.
  • Audio: MP3, WAV, and AAC.
Exact size, duration, codec, and upload restrictions depend on the endpoint and model. Check the relevant API reference before uploading large media.
Use the face asset workflow when a Seedance 2.0 reference image or video contains a human face. The workflow covers public assets, private uploads, Active preprocessing status, and asset://<ASSET_ID> request values.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 provider error reference when the response includes an upstream ModelArk code.