Video generation and task polling

Create and poll asynchronous video tasks such as Seedance.

POST/v1/videos/generations
https://api.hanrouter.ai/v1Manage API keys

URL and authentication

Use https://api.hanrouter.ai/v1 as the OpenAI-compatible Base URL and Authorization: Bearer $HANROUTER_API_KEY. Do not duplicate /v1. All manufacturers use your HanRouter key, not an upstream vendor key.

For the Anthropic SDK and Claude Code, use https://api.hanrouter.ai without /v1; the client appends /v1/messages. Use the OpenAI-compatible interface for Google models.

Video task workflow

Video is usually asynchronous: submit once, save the task ID, poll using the same key, wait for success/failure and download. HTTP 200 means accepted, not necessarily completed. Select a video-output model from GET /v1/models and check group permissions.

Submit a text-to-video task

The studio uses POST /v1/videos/generations with model, prompt, duration and resolution. Replace the placeholder with an available model supporting this protocol. Five seconds and 720p are examples, not universal capabilities; follow channel limits and prices.

Request example
curl --max-time 300 "https://api.hanrouter.ai/v1/videos/generations" \
  -H "Authorization: Bearer $HANROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_VIDEO_MODEL_ID",
  "prompt": "A golden bull runs forward, slow cinematic camera movement",
  "duration": 5,
  "resolution": "720p"
}'

Image to video: starting frame

Compatible channels can add image: {"url":"https://..."}, matching the studio starting-frame input. Replace the example with an upstream-accessible image. Some channels accept data URLs; others require public HTTPS URLs. Format, ratio and size limits depend on the model.

Request example
curl --max-time 300 "https://api.hanrouter.ai/v1/videos/generations" \
  -H "Authorization: Bearer $HANROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_VIDEO_MODEL_ID",
  "prompt": "A golden bull runs forward, slow cinematic camera movement",
  "duration": 5,
  "resolution": "720p",
  "image": {
    "url": "https://example.com/first-frame.png"
  }
}'

Seedance native content protocol

Use content instead of the prompt adapter only when your Seedance channel explicitly supports BytePlus/ModelArk native pass-through. A text block is {type:"text",text:"..."}; a common starting-frame block is {type:"image_url",image_url:{url:"https://..."},role:"first_frame"}. The role nesting may differ by gateway; do not mix another site’s format without checking.

ratio, generate_audio, seed, end frames, reference video/audio, Draft and wait depend on model and channel. Not every Seedance version supports 4–15 seconds, synchronous waiting, audio or continuation; omit fields until support is confirmed.

Request example
curl --max-time 300 "https://api.hanrouter.ai/v1/videos/generations" \
  -H "Authorization: Bearer $HANROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_SEEDANCE_MODEL_ID",
  "content": [
    {
      "type": "text",
      "text": "A cat runs along the beach at sunset"
    }
  ],
  "ratio": "16:9",
  "duration": 5
}'

Save task IDs and polling URLs

Submission may return id, task_id or request_id, with submitted, queued or processing status. Save the full response and actual task ID. The studio polls GET /v1/videos/{id}. An upstream-native channel using /v1/videos/generations/{id} requires explicit route support; another site’s polling path is not automatically available here.

Request example
# Illustrative submission response (not a real task)
{"id":"task-id-from-response","status":"processing"}

# Replace TASK_ID with the ID actually returned
curl "https://api.hanrouter.ai/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $HANROUTER_API_KEY"

Status, results and safe retries

Poll about every five seconds and honor Retry-After. Success may be succeeded/completed; failures may be failed/error/expired/canceled. Follow the actual response. Adapters may return url, video_url, content.video_url, content[].video_url or a result wrapper; do not assume one universal structure. Retain a successful response with no output URL for support.

For 404 check task ID, original key, route and retention before resubmitting. A timeout does not prove no task was created. For 400 check parameters and reference accessibility; 401/403 key/permissions; 402 balance; 429 concurrency; 5xx retain X-Request-Id and redacted errors. Refunds are not guaranteed; actual charges, refunds and billing units follow console usage/orders. Download promptly because URLs can expire.

Request parameters

model
Required string: exact model ID available to your key.
prompt
String: image or prompt-adapter video description; native content depends on channel requirements.
content
Seedance input array: text, images or supported references.
duration
Optional integer: video seconds within model limits.
resolution
Optional string: a resolution supported by the model.
ratio
Optional string: supported aspect ratio, such as 16:9; only for compatible channels.
generate_audio
Optional boolean: generate audio only on compatible models/channels.
seed
Optional integer: random seed; valid range depends on model/channel.

Request example

Examples use configured model IDs. Key group permissions determine access; query GET /v1/models first.

cURL
curl -X POST "https://api.hanrouter.ai/v1/videos/generations" \
  -H "Authorization: Bearer $HANROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "your-model-id",
  "prompt": "A red bicycle beside a tree, slow camera movement",
  "duration": 5,
  "resolution": "720p"
}'

Response example

JSON · illustrative structure
{
  "id": "task-id-from-response",
  "status": "submitted"
}