Flux Videos API Integration Guide

The Flux Videos API uses POST /flux/videos to complete video generation, keyframe image-to-video, video continuation, and draft enhancement. action=generate (default), and mode selects the generation mode; existing POST /flux/tasks is uniformly used to query results.

Currently in Beta. Text-to-video, image-to-video, video continuation, and draft enhancement are available. HTTP 200 and a task ID only indicate that the task has been accepted; you must continue querying for the final result.

1. Obtain an API Token

  1. Register or log in to the 胖狐中转 Console, create an application, and obtain an API Token. A general API Token can call platform services; please confirm that the application has permission to call the Flux service and has an available balance.
  2. View plans and pricing for each operation on the Flux service page. When the balance is insufficient, recharge on the console balance page.
  3. Requests use Authorization: Bearer <your Token>. The Token should be stored in server-side environment variables; do not write it into frontend pages, public repositories, screenshots, or callback URLs.

Apply for an API Token in the console

The code in this article uniformly reads the environment variable:

export ACEDATACLOUD_API_TOKEN='替换为你自己的 API Token'
Item Value
API base URL https://api.ace.324567.xyz
Submit video task POST /flux/videos
Query existing task POST /flux/tasks
Authentication Authorization: Bearer $ACEDATACLOUD_API_TOKEN
Request format Content-Type: application/json

For complete fields and online debugging, see Flux Videos API; for task queries, see Flux Tasks API.

2. Choose an Operation and Input

action mode Input Result
generate (default when action is omitted) t2v prompt Generate video from text
generate i2v prompt, keyframes Generate video from one or more keyframes
generate v2v prompt, start_video Continue based on the input video
generate draft_enhance draft_task_id of a draft you have completed Enhance that draft

The generation model is flux-3, and action is generate (default). Use mode to select text-to-video, image-to-video, video continuation, or draft enhancement.

Common Generation Parameters

Parameter Description
mode Required; t2v, i2v, v2v, or draft_enhance
prompt Required for normal generation; draft enhancement does not allow overriding the original prompt
duration For t2v/i2v, an integer of 5–20 seconds; for v2v, an integer of 5–15 seconds; or auto; the final output duration may differ slightly from the requested value
resolution hd, fhd, qhd, uhd; normal generation defaults to hd, draft enhancement defaults to fhd
aspect_ratio auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16, 9:21
draft Whether to generate a draft first; drafts only support hd
generate_audio Whether to generate synchronized audio; false is a valid value, please retain the explicit boolean value
safety_tolerance Optional; an integer from 0–4
async Recommended to set to true, immediately return the platform task ID, then poll for results
callback_url Optional; an HTTP(S) address that receives the final JSON result; it will also be accepted asynchronously after being set

Asset URLs must be readable by the service. If using temporary signed URLs, reserve sufficient validity time for downloading and processing. Do not use webpage URLs as image or video file URLs.

3. Text-to-Video: Complete Tested Request and Result

The following request was successfully executed on the production API before the price adjustment on 2026-10-02. Omitting action verified the default generation behavior; async=true avoids waiting for a long HTTP connection.

curl -X POST 'https://api.ace.324567.xyz/flux/videos' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "flux-3",
    "mode": "t2v",
    "prompt": "A small toy sailboat floating on calm blue water in warm morning light, steady camera, no text.",
    "duration": 5,
    "resolution": "hd",
    "draft": true,
    "async": true
  }'

Acceptance response (real task ID):

{
  "task_id": "4341eb66-3845-4972-bb86-712a6cfae845",
  "trace_id": "b0f851bd-0925-43ca-acc3-6f634c70d607"
}

Save the task_id in your own response and continue querying; do not use the task ID from the documentation example to query results from other accounts.

curl -X POST 'https://api.ace.324567.xyz/flux/tasks' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"action":"retrieve","id":"替换为本次返回的 task_id"}'

The response field returned by the task query contains the final business result. The following is the successfully tested response from this test, with the outer task metadata omitted. The video URL in the documentation has been replaced with a copy of the same file on a long-term example CDN (SHA-256 consistent); actual calls will return the result URL for the current task:

{
  "success": true,
  "task_id": "4341eb66-3845-4972-bb86-712a6cfae845",
  "trace_id": "b0f851bd-0925-43ca-acc3-6f634c70d607",
  "data": [
    {
      "id": "4341eb66-3845-4972-bb86-712a6cfae845",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/4341eb66-3845-4972-bb86-712a6cfae845-5f4391e1942c.mp4",
      "seconds": 5.041667,
      "width": 1280,
      "height": 704,
      "fps": 24,
      "draft_task_id": "4341eb66-3845-4972-bb86-712a6cfae845"
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5.041667,
    "output_mp_seconds": 4.3326825781250005,
    "mode": "t2v",
    "resolution": "hd",
    "draft": true
  },
  "cost": {
    "amount": 2.6884689277500002,
    "currency": "credit",
    "list_amount": 2.9871876975000005
  }
}

View the video from this test. Media inspection confirms the output is an MP4 at 1280×704, 24 fps, and 5.041667 seconds, with a file size of 2,607,276 bytes.

Response field Purpose
success Whether the final task succeeded; a task_id returned during the acceptance stage does not mean success=true
task_id Platform task ID, used for polling and business idempotency handling
trace_id Provide to support personnel when troubleshooting
data[].video_url Accessible video result URL
data[].seconds/width/height/fps Actual output duration, dimensions, and frame rate measured by the server
data[].draft_task_id Input ID for draft enhancement; appears only when a reusable draft is returned
usage Final billable usage; do not use the requested duration to overwrite the actual seconds
cost.amount Final Credits charged for this request; currency=credit does not mean US dollars
cost.list_amount Credits before the application user's consumption discount; returned when applicable

This is a historical test before the price adjustment: list_amount=2.9871876975 Credits, and the account had a 10% consumption discount at the time, resulting in an actual amount=2.68846892775 Credits. The new price on 2026-10-02 has been reduced by approximately 6.33%; the same 5.041667-second draft costs 2.798125185 Credits at the current price (before the consumption discount), or 2.5183126665 Credits if a 10% consumption discount still applies. Historical task billing is not recalculated. Plans and discounts for other accounts may differ; this is not a fixed USD price for all users.

4. Image-to-Video: Standard and Timed Keyframes

The following are parameter examples. You need to replace the asset URLs; they are not a declaration that this example has already been successfully executed. After generation is complete, query it following the process above; the result structure is the same.

Use a standard array for one or two images:

{
  "action": "generate",
  "model": "flux-3",
  "mode": "i2v",
  "prompt": "The camera slowly moves around the product in soft studio light.",
  "keyframes": ["https://example.com/first-frame.jpg"],
  "duration": 5,
  "resolution": "hd",
  "generate_audio": false,
  "async": true
}

When specifying keyframe times, use [seconds, image URL] pairs:

{
  "action": "generate",
  "model": "flux-3",
  "mode": "i2v",
  "prompt": "A smooth transition from morning light to a warm sunset.",
  "keyframes": [[0, "https://example.com/start.jpg"], [5, "https://example.com/end.jpg"]],
  "duration": 5,
  "resolution": "hd",
  "async": true
}

1–10 keyframes are allowed. Timed arrays must be in increasing time order, with times from 0–20 seconds; standard URLs and timed items cannot be mixed. Three or more standard keyframes must explicitly specify duration and cannot use auto.

Image-to-Video Test Output

The matching input for this test is as follows (only the complete base64 is replaced with descriptive text; all other fields are from the actual request):

{
  "async": true,
  "action": "generate",
  "model": "flux-3",
  "prompt": "The toy sailboat drifts slowly across calm water. A steady camera, gentle daylight, no people or text.",
  "duration": 5,
  "resolution": "hd",
  "generate_audio": false,
  "draft": false,
  "mode": "i2v",
  "keyframes": [
    "<下图 PNG 文件的原始 base64 字符串>"
  ]
}

Reference keyframe for this image-to-video test

After downloading this PNG keyframe, you can use Python's base64.b64encode(image_bytes).decode("ascii") to obtain the raw string and place it in the keyframes array. Do not use the descriptive text in the documentation as image input.

The following is the real final response for the production task on 2026-10-01 (not a simulated response); only the video URL has been replaced with a long-term example copy with the same hash. The test input used the raw base64 string of a 1280×720 PNG as a single keyframe; the URL input above is an independent parameter example.

{
  "success": true,
  "task_id": "b1106de8-d586-4e23-b489-381e2f86a10f",
  "trace_id": "f62d5c56-cfb2-4f8f-b339-ef019d4c0d10",
  "data": [
    {
      "id": "b1106de8-d586-4e23-b489-381e2f86a10f",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/b1106de8-d586-4e23-b489-381e2f86a10f-bef14458cc9d.mp4",
      "seconds": 5.041667,
      "width": 1280,
      "height": 704,
      "fps": 24
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5.041667,
    "output_mp_seconds": 4.3326825781250005,
    "mode": "i2v",
    "resolution": "hd",
    "draft": false
  },
  "cost": {
    "amount": 7.617328628625,
    "currency": "credit",
    "list_amount": 8.46369847625
  }
}

View the actual test video.

5. Video Continuation

Pass the address of an existing video file in start_video, use mode=v2v, with a maximum duration of 15 seconds.

{
  "action": "generate",
  "model": "flux-3",
  "mode": "v2v",
  "prompt": "Continue the sailboat drifting forward with the same steady camera.",
  "start_video": "https://example.com/source.mp4",
  "duration": 5,
  "resolution": "hd",
  "async": true
}

Actual Video Continuation Test Output

The complete actual test input for this run is as follows; when reproducing draft enhancement, you must replace it with your own draft ID. The material URL uses a long-term example copy of the same file:

{
  "action": "generate",
  "model": "flux-3",
  "mode": "v2v",
  "start_video": "https://cdn.acedata.cloud/assets/examples/flux/b41293be-94c0-4dc7-9f39-ce04f0a8798d-c055a3079059.mp4",
  "prompt": "Continue the same sailboat drifting gently across calm water in the same continuous steady shot.",
  "duration": 5,
  "resolution": "hd",
  "generate_audio": false,
  "async": true
}

The following is the actual final response from a production task on 2026-10-01 (not a simulated response); only the video URL has been replaced with a long-term example copy with the same hash.

{
  "success": true,
  "task_id": "8af9aa42-7e4d-47a4-bd61-144d97440c91",
  "trace_id": "4fb49afc-abca-4039-bbaa-adb66e293544",
  "data": [
    {
      "id": "8af9aa42-7e4d-47a4-bd61-144d97440c91",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/8af9aa42-7e4d-47a4-bd61-144d97440c91-a512d6574811.mp4",
      "seconds": 5,
      "width": 1280,
      "height": 704,
      "fps": 24
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5,
    "output_mp_seconds": 4.296875,
    "mode": "v2v",
    "resolution": "hd",
    "draft": false
  },
  "cost": {
    "amount": 18.219375,
    "currency": "credit",
    "list_amount": 20.24375
  }
}

View the actual test video.

The actual test input start_video is the completed draft video, and the other parameters are duration=5, resolution=hd, generate_audio=false.

6. Draft First, Then Enhance

  1. Generate a draft with draft=true, resolution=hd, and wait for success.
  2. Retrieve the platform draft ID from the final data[0].draft_task_id.
  3. Submit an enhancement request using application credentials under the same ownership:
{
  "action": "generate",
  "model": "flux-3",
  "mode": "draft_enhance",
  "draft_task_id": "替换为自己的已完成草稿 ID",
  "resolution": "fhd",
  "async": true
}

Draft enhancement cannot pass prompt, duration, aspect_ratio, version, generate_audio, draft, keyframes, or start_video to override the original content. Draft cache is a temporary resource, so please enhance it promptly; permanent storage or a fixed retention period is not guaranteed. Drafts not belonging to you/the current application, incomplete drafts, and expired caches cannot be reused. The draft and enhancement are two separate tasks and are billed separately upon success.

Actual Draft Enhancement Test Output

The complete actual test input for this run is as follows; when reproducing draft enhancement, you must replace it with your own draft ID. The material URL uses a long-term example copy of the same file:

{
  "action": "generate",
  "model": "flux-3",
  "mode": "draft_enhance",
  "draft_task_id": "b41293be-94c0-4dc7-9f39-ce04f0a8798d",
  "resolution": "hd",
  "async": true
}

The following is the actual final response from a production task on 2026-10-01 (not a simulated response); only the video URL has been replaced with a long-term example copy with the same hash.

{
  "success": true,
  "task_id": "1db6243b-4a05-4484-828c-25bb17de7108",
  "trace_id": "64f93fa1-8d18-4c8b-a6d2-888009eb7cfa",
  "data": [
    {
      "id": "1db6243b-4a05-4484-828c-25bb17de7108",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/1db6243b-4a05-4484-828c-25bb17de7108-058d92166607.mp4",
      "seconds": 5.041667,
      "width": 1280,
      "height": 704,
      "fps": 24
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5.041667,
    "output_mp_seconds": 4.3326825781250005,
    "mode": "t2v",
    "resolution": "hd",
    "draft": false
  },
  "cost": {
    "amount": 7.617328628625,
    "currency": "credit",
    "list_amount": 8.46369847625
  }
}

View the actual test video.

The actual test input uses your own draft_task_id=b41293be-94c0-4dc7-9f39-ce04f0a8798d, resolution=hd; the final usage.mode=t2v indicates the original draft mode. This task is billed separately from the original draft.

7. Python End-to-End Call

Install requests, set your own Token, and run the script below to complete “submit once → poll → output video URL”. Both querying and network retries should use the original task_id to avoid repeatedly submitting billable tasks.

import os
import time
import requests

base_url = "https://api.ace.324567.xyz"
headers = {
    "Authorization": "Bearer " + os.environ["ACEDATACLOUD_API_TOKEN"],
    "Accept": "application/json",
}
payload = {
    "action": "generate",
    "model": "flux-3",
    "mode": "t2v",
    "prompt": "A small toy sailboat floating on calm blue water in warm morning light.",
    "duration": 5,
    "resolution": "hd",
    "draft": True,
    "async": True,
}
submitted = requests.post(base_url + "/flux/videos", json=payload, headers=headers, timeout=120)
submitted.raise_for_status()
accepted = submitted.json()
if accepted.get("error"):
    raise RuntimeError(accepted["error"])
task_id = accepted["task_id"]
print("Task ID:", task_id)  # 持久化保存，用于恢复轮询

# 30 分钟是本示例的客户端等待上限，不是服务的完成时限承诺。
deadline = time.monotonic() + 30 * 60
while time.monotonic() < deadline:
    polled = requests.post(
        base_url + "/flux/tasks",
        json={"action": "retrieve", "id": task_id},
        headers=headers,
        timeout=30,
    )
    polled.raise_for_status()
    task = polled.json()
    if task.get("error"):
        raise RuntimeError(task["error"])
    result = task.get("response") or task.get("result")
    if isinstance(result, dict) and result.get("success") is True:
        print("Video:", result["data"][0]["video_url"])
        print("Usage:", result.get("usage"))
        print("Cost:", result.get("cost"))
        break
    if isinstance(result, dict) and result.get("error"):
        raise RuntimeError(result["error"])
    time.sleep(10)
else:
    raise TimeoutError("Still processing; resume polling with task_id=" + task_id)

After a network timeout, do not treat an unknown status as a failure and immediately resubmit. If you have obtained a task_id, continue querying that task; record the task_id and trace_id for troubleshooting. The polling API itself does not charge generation fees.

8. Using Callbacks

Add callback_url when submitting. After the task is completed, the final JSON result will be POSTed to that address. The success structure is consistent with the aforementioned response; failures include error.

{
  "action": "generate",
  "model": "flux-3",
  "mode": "t2v",
  "prompt": "A small sailboat on calm water.",
  "duration": 5,
  "resolution": "hd",
  "draft": true,
  "callback_url": "https://your-server.example/flux-callback"
}

The callback address should be accessible from the public internet. After receiving the notification, process it idempotently based on task_id and return 2xx as soon as possible; business processing can be queued. This document does not declare that callbacks have signature authentication: before performing sensitive operations such as granting business benefits, use your own Token to query the same task and verify the result. If the callback is not received, you can also continue polling; do not regenerate.

9. Current Billing and Pricing Table

Updated 2026-10-02: Unit prices for all tiers of this video API have been reduced by approximately 6.33%. The metering method, plans, and consumption discount rules remain unchanged. The cost in the historical measured response above is the bill at task completion and does not represent the current quotation.

Video generation is billed based on actual output seconds. Below are the current Credits unit prices before account consumption discounts are applied, consistent with the rules on the Flux pricing page.

Operation/Mode Resolution Credits Unit Price
t2v / i2v draft hd 0.555 / sec
v2v draft hd 1.11 / sec
t2v / i2v / corresponding draft enhancement hd 1.5725 / sec
Same as above fhd 2.6825 / sec
Same as above qhd 3.7 / sec
Same as above uhd 7.4 / sec
v2v / corresponding draft enhancement hd 3.7925 / sec
Same as above fhd 4.9025 / sec
Same as above qhd 6.0125 / sec
Same as above uhd 8.7875 / sec

USD conversion: actual cost (USD) = cost.amount (Credits) × plan price / plan amount. Top-up tiers and consumption discounts affect the actual price; Credits cannot be directly treated as USD. Failed tasks are not charged generation fees; the final amount is subject to the completion result and console call records.

10. Frequently Asked Questions and Troubleshooting

Situation Recommendation
Parameter error (400) Check action=generate, mode, duration, and keyframe format; do not mix fields from different generation modes
Authentication error (401) Check the Bearer Token, application permissions, and whether the credentials are valid
Content moderation rejection (403) Adjust the material and prompt; do not repeatedly submit them unchanged
Rate limit (429) Reduce concurrency and retry with backoff
service_unavailable (503) The current operation is unavailable; accepted asynchronous tasks may report this error in the final response
task_id has been returned but there is no video yet Continue querying response; do not treat HTTP 200 as generation completion
Draft cannot be reused Confirm the current user/application, that the task has completed, that the original request used draft=true, and check whether the temporary cache is still valid

When providing feedback, include the task_id, trace_id, request time, and redacted parameters. Do not send the API Token. For more methods, see the Flux MCP Integration Guide.