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를 사용하고 본문(body)이 변경되지 않은 경우, 재시도해도 생성 ID는 동일하게 유지됩니다. 상태를 조회하려면 Flux 생성 ID를 사용하세요. provider_task_id는 지원팀 문의 시 참고용으로 사용될 수 있으며, Flux 조회 키는 아닙니다.

오류 발생 시 Flux error.code는 유지되며, 가능한 경우 소스(source) 및 제공업체(provider) 세부 정보가 추가됩니다. 제공업체의 비즈니스 코드, 실패 코드, HTTP 상태는 Flux의 HTTP 상태와는 별개입니다. 상태 조회가 성공했다고 해서 생성 작업이 성공한 것을 의미하지는 않습니다.

재시도하기 전에 오류 설명과 청구 상태를 확인하세요. 잘못된 입력값을 수정하고, 속도 제한(rate limit)이 해제될 때까지 기다리거나, 결과를 알 수 없는 경우 원본 작업을 조회하세요. 업스트림(Upstream) 계정 또는 설정 오류는 Flux 지원팀의 도움이 필요하며, 새로운 Flux API 키를 발급받거나 Flux 크레딧을 추가로 구매해서 해결할 수 있는 문제가 아닙니다.

지원이 필요한 경우, API 로그에서 문제 해결 정보를 복사하세요. 가능한 경우 HTTP 요청 ID, Flux 생성 ID, provider task 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.