Video generation and task polling
Create and poll asynchronous video tasks such as Seedance.
/v1/videos/generationshttps://api.hanrouter.ai/v1Manage API keysURL 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.
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.
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.
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.
# 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 -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
{
"id": "task-id-from-response",
"status": "submitted"
}