Seedance 2.5 Flash API Tutorial: Async Jobs, Limits, Errors

AIHubMix8 min read
Seedance 2.5 Flash API Tutorial: Async Jobs, Limits, Errors

Use doubao-seedance-2-5-flash with POST /ai/v1/videos, poll the task, then download its result. The current AIHubMix schema exposes 480p/720p output, 4–30-second clips, and up to 10 image, 5 video, and 5 audio references. Older clients using /v1/videos need to change the endpoint as well as the model ID.

This guide was checked on November 16, 2026. Both the short ID above and doubao-seedance-2-5-flash-261115 returned a model schema and rejected a 1080p request with 400 schema_violation. A separate 4-second 480p creation attempt returned 402 insufficient_quota; it did not generate a video. The workflow below follows the current schema and documentation, but successful generation, latency, MOV output, and editing were not verified end to end in this check.

Prerequisites and schema discovery

The Seedance 2.5 Flash model page lists the model under the short ID used throughout this guide. Before submitting a task:

  1. Enable asynchronous media tasks in the AIHubMix console. The documented error for an account without this feature is 403 async_not_enabled.
  2. Ensure the API key has access and the account has enough credit. The live check returned 402 insufficient_quota with the message Your account has insufficient quota. Add credits and try again.
  3. Export AIHUBMIX_API_KEY in your shell. Keep the key out of source files and browser code.
  4. Retrieve the current schema; the discovery request needs no authentication.
curl --fail-with-body -sS \
  'https://aihubmix.com/call/schema/models/doubao-seedance-2-5-flash/endpoints' \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'

The November 16 schema lists only /ai/v1/videos for Flash. It accepts resolution values 480p and 720p (default 720p), an integer duration from 4 through 30, or -1 for model-selected duration. Use an explicit duration when you need a predictable budget.

Create, poll, and download

The AIHubMix Video Generation API separates creation, status queries, and downloads. An HTTP success from creation means a task was accepted; only status: "completed" confirms completion. A query can return HTTP 200 while the task itself has status: "failed".

Submit a text-to-video task

This example requests a 10-second 720p 16:9 product clip with audio. It uses text only, so it does not depend on reference images hosted elsewhere.

curl --fail-with-body -sS -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": true
  }'

Store the returned task id immediately. Poll GET /ai/v1/videos/{id} every 15 seconds until completed, failed, or cancelled. Use the video detail route for active polling: it refreshes provider state, while the unified task list is not a substitute for that check. Download through GET /ai/v1/videos/{id}/content after completion, using the same Bearer header.

A complete Python client

Install the dependency with python3 -m pip install requests, save the following as seedance_flash.py, then run python3 seedance_flash.py in the shell containing your API key. This example implements the documented flow; the quota error above prevented a complete generation test.

import os
import time
from pathlib import Path

import requests

BASE_URL = "https://aihubmix.com"
HEADERS = {
    "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
    "Content-Type": "application/json",
}
PAYLOAD = {
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": True,
}

# Submit once. A network timeout does not prove that creation failed.
response = requests.post(
    f"{BASE_URL}/ai/v1/videos", headers=HEADERS, json=PAYLOAD, timeout=60
)
response.raise_for_status()
task = response.json()
task_id = task["id"]
print(f"Task ID: {task_id}", flush=True)

deadline = time.monotonic() + 20 * 60
while task["status"] not in {"completed", "failed", "cancelled"}:
    if time.monotonic() >= deadline:
        raise TimeoutError(f"Still waiting for {task_id}; query it again, do not recreate it.")
    time.sleep(15)
    response = requests.get(
        f"{BASE_URL}/ai/v1/videos/{task_id}", headers=HEADERS, timeout=30
    )
    response.raise_for_status()
    task = response.json()

if task["status"] != "completed":
    raise RuntimeError(f"Task {task_id}: {task.get('error') or task['status']}")

response = requests.get(
    f"{BASE_URL}/ai/v1/videos/{task_id}/content", headers=HEADERS, timeout=120
)
response.raise_for_status()
Path("seedance_flash_10s.mp4").write_bytes(response.content)
print("Saved seedance_flash_10s.mp4")

The 20-minute deadline is a client-side waiting limit, not a server cancellation or a generation-time guarantee. If polling or downloading fails, retain the task ID and retry that operation. Do not automatically submit another generation request after a timeout or an uncertain provider state.

At BytePlus's official online inference rates, Flash costs $7.00 per million tokens without video input or $4.30 with video input at 480p/720p. For the text-only example, the estimate is 10 × 1280 × 720 × 24 / 1024 = 216,000 tokens: $1.51 on Flash versus $2.31 on flagship 2.5 at 720p. These are computed BytePlus estimates, not a measured AIHubMix bill.

References and webhooks

To guide a clip with media, add input_references entries containing a type (image_url, video_url, or audio_url) and a url pointing to your accessible media. The schema caps those types at 10 / 5 / 5. For first/last-frame control, use frame_images instead; each entry has a frame_type and nested image_url.url. Do not mix non-empty frame_images and input_references. Frame workflows require aspect_ratio: "adaptive", and a last frame requires a first frame.

The Async Tasks documentation describes HTTPS callbacks via webhook_url. Flash's current schema includes that field but omits webhook_events_filter and sets additionalProperties: false, so omit the filter when following this model schema. The documented default sends completed, failed, and cancelled. Delivery is at least once, with up to six attempts and retry intervals of 1, 4, 16, 64, and 256 seconds; deduplicate on event_id. Task-level callbacks have no separate signing secret, so query the task to confirm its final state. The documentation describes account-level subscriptions for applications that need signature verification.

Errors: what was measured and what the docs describe

1080p: a measured schema rejection

Both AIHubMix model IDs returned HTTP 400 for a 4-second request with resolution: "1080p". The returned error fields were:

{
  "error": {
    "code": "schema_violation",
    "message": "`resolution` must be one of: 480p, 720p, null.",
    "type": "invalid_request_error"
  }
}

The response also contained a request trace ID, omitted here. This is an observed gateway rejection, not an inferred upstream error. It establishes neither successful generation nor a speed measurement.

Other constraints below come from the current Flash schema; these invalid combinations were not separately submitted in the live check.

Input problem Schema requirement Fix
4K output 480p or 720p Lower resolution
Too many references 10 images / 5 videos / 5 audio Reduce the set
Two reference arrays One non-empty array Choose a workflow
Last frame alone First frame also required Supply both frames
Fixed ratio with frames Adaptive ratio Use adaptive

Real-person references: use verified assets

AIHubMix documents doubao_real_person_required when Doubao returns its specific privacy rejection for a real-person image. This error was not triggered in this check. Its documented message is:

This request uses a real-person image. Complete real-person verification and use an active asset reference. See https://docs.aihubmix.com/cn/api/doubao-real-person-assets.

Follow the Doubao Real-Person Assets Guide: create a group at /ai/v1/asset-groups, create a verification session at /ai/v1/asset-groups/{id}/verification-sessions, have the depicted person complete the web verification, register the asset at /ai/v1/asset-groups/{id}/assets, and wait until it is active. Use asset://<ASSET_ID> in the generation reference. A raw photo URL is not a substitute for the consent and asset workflow.

Quota, request size, and downloads

The measured 402 insufficient_quota prevented the valid-resolution request from reaching generation. Add credit before trying again; changing a correct prompt or model ID does not resolve this response. 403 async_not_enabled is a different, documented prerequisite error requiring activation in the console.

AIHubMix documents a 32 MiB request-body limit and 413 request_too_large. Public URLs keep Base64 expansion out of your request body, although the referenced media still has to satisfy the model's own size and format limits.

Save a completed video promptly. AIHubMix's existing Seedance 2.5 integration guide warns that output URLs are short-lived, roughly 30 minutes; a fixed Flash retention period was not verified here. The video API can return expires_at: null, which does not promise indefinite storage. Its documented download errors include 410 artifact_expired and 429 too_many_downloads. If a download has a temporary service error, retry the download against the existing task rather than generating the clip again.

Migration traps that a valid request can still hit

The Volcengine Seedance 2.5 guide explicitly includes Flash in the family and confirms MOV output, editing, and extension, but those vendor capabilities need to be separated from what was verified through the gateway.

  • MOV and editing fields are exposed, not end-to-end tested here. Flash's schema accepts extra.output_format: "mp4" or "mov" and extra.omni_reference_task_type values auto, reference, edit, and extend. If you explicitly send the task-type field, the schema requires non-empty input_references. edit additionally needs a video reference, adaptive ratio, and duration: -1; extend needs a video reference and adaptive ratio.
  • Explicit task type does not guarantee the model agrees. Ark documents asynchronous InvalidParameter.TaskTypeConstraint when inferred task type and parameters conflict, and InvalidParameter.TaskTypeMismatch when the inferred type differs from an explicitly requested one. The exact AIHubMix mapping was not measured; inspect the returned task error rather than assuming one gateway code.
  • Flash has no Draft promotion. The vendor limits the two-stage 480p Draft-to-final workflow to flagship 2.5. Flash does not support it, and the current AIHubMix schemas for both models omit draft and draft_task.
  • Video input changes billing. Official billing uses input plus output video duration and can impose a minimum token floor. The $4.30/M rate is not a promise that a video-guided job costs less than an otherwise identical text-only job. Check actual usage and account billing rather than relying on the formula alone.
  • Some descriptions remain ambiguous. Flash's gateway schema exposes extra.priority, extra.safety_identifier, and extra.tools, but their descriptions still say “2.0 series only.” Ark's create-task reference lists priority and tools for the 2.5 family too. Schema exposure alone does not verify their effect on AIHubMix; validate the particular feature before relying on it in production.

Pre-flight checklist

  • Enable asynchronous tasks and check account credit.
  • Use the short Flash ID with /ai/v1/videos and retrieve its current schema.
  • Choose 480p or 720p and an explicit duration within 4–30 seconds.
  • Keep references within 10 images, 5 videos, and 5 audio clips.
  • Keep frame references separate and use adaptive ratio for them.
  • Route real-person likeness references through verified active assets.
  • Store the task ID, inspect terminal task status, and download promptly.
  • Retry queries or downloads against an existing task when its generation state is uncertain.

Frequently asked questions

Can I use the OpenAI-compatible /v1/videos path for Flash?
The current Flash schema lists only /ai/v1/videos. Use that native asynchronous path for the examples in this guide.

Why does a frame-image request fail with aspect_ratio: "16:9"?
Flash's schema requires aspect_ratio: "adaptive" when non-empty frame_images are provided. A last frame also requires a first frame, and frame references cannot be combined with non-empty input_references.

How do I fix doubao_real_person_required?
Follow the personal verification and asset registration workflow, wait for the asset to become active, and reference it with an asset URI. The code denotes Doubao's specific privacy rejection; it was not reproduced in this check.

Why can a short reference video cost more than the formula predicts?
The vendor's billing rules can apply a minimum token floor when the input includes video. The formula is an estimate; check actual consumption and the account's billing records for the charged amount.

Do failed generations or moderation rejections cost money?
Official BytePlus and Volcengine billing rules charge successful generations and state that failed generation and content-moderation rejection are not billed. AIHubMix's error documentation advises checking billing records for historical charges; no successful or failed generation bill was measured here.

How long do I have to download a Flash result?
Download it immediately after completion. The existing Seedance 2.5 guide warns of roughly 30-minute URLs, but Flash's exact retention was not verified, and a null expiry field does not mean the result is permanent.

Are MOV output and edit/extend supported through AIHubMix?
The current Flash schema exposes the corresponding fields under extra, and the vendor documents these capabilities. Their end-to-end behavior through AIHubMix was not verified because the creation test stopped at an insufficient-quota response.

Keep reading: the Seedance 2.5 Flash series

Sources

Documentation and schema checked November 16, 2026; validation responses recorded at 08:26 UTC. Prices are official BytePlus estimates, not measured gateway charges.

One gateway to multiple AI providers. Built for production.

Visit AIHubMix