API

1. Create a key

Create a key in API Key and save it as a server-side environment variable.

export FLUX_API_KEY="YOUR_FLUX_API_KEY"

2. Check your connection

This request reads your balance and does not spend credits.

curl https://api.flux-context.org/api/v1/balance \
  -H "Authorization: Bearer $FLUX_API_KEY"

3. Create a generation

Choose a model to see its parameters and a complete request example.

4. Poll and download

Save the returned request ID and query approximately every 10 seconds. Background work continues even when you stop polling.

curl https://api.flux-context.org/api/v1/generations/REQUEST_ID \
  -H "Authorization: Bearer $FLUX_API_KEY"

When status is succeeded, download each URL in results. Response excerpt:

{
  "id": "REQUEST_ID",
  "status": "succeeded",
  "results": [
    {
      "url": "https://api.flux-context.org/api/v1/files/SIGNED_TOKEN",
      "url_expires_at": "2026-09-10T11:42:18Z",
      "expires_at": "2026-10-10T10:42:18Z",
      "expired": false,
      "media_type": "image",
      "content_type": "image/png",
      "size_bytes": 1234567,
      "width": 1024,
      "height": 1024
    }
  ]
}

Stop polling when the status is succeeded or failed. For failed tasks, read error and billing for the reason and final credit settlement.

Download links last one hour. Query again for a fresh link. Files are retained for 30 days after transfer; file expiry does not change generation or billing records. Video results use media_type video and content_type video/mp4; save them with a .mp4 extension. Downloads support HEAD and single byte-range requests for playback and resuming.

curl --fail --location "$RESULT_URL" --output result.png

Credits and settlement

No subscription is required. API generations spend subscription credits first, then purchased credits. Gift credits cannot be used, including for additional video charges. GET /balance returns credits_available for these eligible pools only; breakdown.giftRemaining is informational and is not included. Refunds follow the original charge.

Fixed requests are charged upfront. Seedance 2.5 editing reserves credits and settles automatically after generation. Billing includes credits_precharged, credits_additional, credits_refunded, credits_final and settlement_status. credits_charged remains the total debited before refunds. credits_final is null while pending. If settlement_mode is precharge_retained, the precharge remains debited and results are available while billing awaits review.

Missing final billing data stays pending and is retried in the background. No manual log checks are required. Results are available after settlement. File expiry does not refund a successful generation.

Reference media

Supply public HTTPS URLs, without duration fields. Flux measures MP4/MOV video and MP3/WAV/M4A audio before charging. References must stay available until generation finishes. Requests use up to 3 concurrent probes, a 20-second deadline, an 8 MiB metadata budget per file and 32 MiB in total. Range support is recommended; small files also work without it.

INVALID_REFERENCE_MEDIA (HTTP 400) means media could not be read reliably or exceeded a model constraint. No task was created or credits charged. Check the URL, file format and duration, then retry.

Common request headers

A network timeout does not prove creation failed. Use the optional retry header when automatically retrying POST requests. The Python example handles it for you.

Errors & limits

每次 HTTP 请求都会有一个 request_id 和 X-Request-Id 请求头。当使用相同的 Idempotency-Key 且请求体不变时，多次重试的生成 ID 会保持一致。请使用 Flux 生成 ID 来查询任务状态；provider_task_id 只是一个可选的辅助参考信息，不能作为 Flux 的查询键。

错误信息会保留 Flux 的 error.code，并在可用时附加上游来源和供应商的详细信息。请注意，供应商的业务代码、失败代码和 HTTP 状态与 Flux 的 HTTP 状态是不同的。成功查询到任务状态，不代表生成任务本身也成功了。

重试前，请仔细阅读错误说明和计费状态。请修正无效的输入、等待速率限制解除，或在结果未知时查询原始任务的状态。如果遇到上游账户或配置错误，请联系 Flux 技术支持，而不是尝试创建新的 Flux API 密钥或购买更多 Flux 积分。

如需技术支持，请从 API 日志中复制用于排查问题的信息。请务必提供 HTTP 请求 ID、Flux 生成 ID 以及（若有）供应商任务 ID。切勿分享您的 API 密钥、Authorization 请求头或任何私密的输入数据。

These are default limits. Your effective limits appear in Overview and GET /balance. All keys share the account limit. HTTP 429 includes Retry-After: 60 and a limit object with scope and value. For TOO_MANY_TASKS, wait for existing generations to finish; 60 seconds does not guarantee a slot.

SUBMISSION_NOT_CONFIRMED is not a confirmed failure. Keep the original request ID and query its status. Temporary query errors do not trigger refunds.