> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gengen.farm/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Answers to common GENGEN authentication, billing, generation, troubleshooting, file, and asset questions.

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

* [Authentication and API keys](#authentication-and-api-keys)
* [Balance and billing](#balance-and-billing)
* [Video generation](#video-generation)
* [Troubleshooting and errors](#troubleshooting-and-errors)
* [Files and assets](#files-and-assets)
* [Error reference](#error-reference)

## Authentication and API keys

<AccordionGroup>
  <Accordion title="How do I get an API key?">
    Go to the [GENGEN Dashboard](https://gengen.farm/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.
  </Accordion>

  <Accordion title="What is the base URL and how do I authenticate?">
    All requests use this base URL:

    ```text theme={"dark"}
    https://gengen.farm/api/gengen/v1
    ```

    Add an `Authorization` header to every request:

    ```http theme={"dark"}
    Authorization: Bearer gengen_live_xxxxxxxxxxxxxxxx
    Content-Type: application/json
    ```

    See [Authentication](/authentication) for server-side examples and key-handling guidance.
  </Accordion>

  <Accordion title="My API key stopped working. What should I check?">
    * Confirm the key has not been revoked in the **API Keys** area of the [Dashboard](https://gengen.farm/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.
  </Accordion>
</AccordionGroup>

## Balance and billing

<AccordionGroup>
  <Accordion title="How do I check my current balance?">
    Open the [Dashboard](https://gengen.farm/dashboard) and view the **Overview** area. It shows the current wallet balance and recent transaction history.
  </Accordion>

  <Accordion title="How is usage charged?">
    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](/pricing) for current customer prices. Only the final charged price is relevant to API users.
  </Accordion>

  <Accordion title="What happens when my available balance is insufficient?">
    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](https://gengen.farm/dashboard) before submitting another billable request.
  </Accordion>
</AccordionGroup>

## Video generation

<AccordionGroup>
  <Accordion title="Video generation is asynchronous. How does polling work?">
    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.

    ```javascript theme={"dark"}
    const task = await createTask(payload);

    while (true) {
      const result = await getTask(task.id);

      if (result.status === "succeeded") {
        return result.outputs.videos[0];
      }

      if (result.status === "failed" || result.status === "cancelled") {
        throw new Error(`Task ended with status: ${result.status}`);
      }

      await sleep(3000);
    }
    ```
  </Accordion>

  <Accordion title="How long does video generation take?">
    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.
  </Accordion>

  <Accordion title="What generation modes are supported?">
    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](/api-reference/byteplus/video-generation/create-task) for the normalized request structure.
  </Accordion>

  <Accordion title="What resolutions and durations are supported?">
    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`.
  </Accordion>

  <Accordion title="My task is stuck in processing. What should I do?">
    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.
  </Accordion>

  <Accordion title="My task failed content moderation. What can I do?">
    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](/face-assets-video-generation).
  </Accordion>
</AccordionGroup>

## Troubleshooting and errors

<AccordionGroup>
  <Accordion title="The input image may contain a real person">
    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](/face-assets-video-generation).
  </Accordion>

  <Accordion title="The output video may be related to copyright restrictions">
    Replace the source material or revise the prompt so the request does not reproduce protected content. Submit only material you have the right to use.
  </Accordion>

  <Accordion title="The output audio may contain sensitive information">
    Disable `controls.generateAudio`, then submit the generation request again.
  </Accordion>

  <Accordion title="What are the rate limits?">
    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.
  </Accordion>

  <Accordion title="I am receiving 429 responses. What should I do?">
    * 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.
  </Accordion>

  <Accordion title="I am receiving 401 responses. What should I do?">
    * 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.
  </Accordion>

  <Accordion title="I received an error that is not listed here. What should I do?">
    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](/help/errors) for the standard error envelope and retry guidance.
  </Accordion>
</AccordionGroup>

## Files and assets

<AccordionGroup>
  <Accordion title="What is the difference between Files and Asset Groups?">
    **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.
  </Accordion>

  <Accordion title="What media formats can I use?">
    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.
  </Accordion>

  <Accordion title="How do I use a real person's photo to generate videos?">
    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](/face-assets-video-generation).

    When the subject needs to provide explicit authorization, create a [Real-Person Verification Session](/api-reference/byteplus/assets/create-real-human-session), direct the subject to the returned H5 URL, and then [retrieve the verification result](/api-reference/byteplus/assets/get-real-human-result).
  </Accordion>

  <Accordion title="An uploaded asset is still processing. Is it ready to use?">
    No. Poll [Get asset](/api-reference/byteplus/assets/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.
  </Accordion>
</AccordionGroup>

## 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](/help/errors) for response format, status categories, and retry guidance. Search the [BytePlus provider error reference](/help/provider-errors) when the response includes an upstream ModelArk code.