Video Tasks

Revision 3 · Updated 2026-11-12 · 7 min read

Submit and query asynchronous video tasks through Runtoken.

Prerequisites#

Before you start, prepare:

A platform API key and an available video model ID.
The selected model’s native JSON request body and an HTTP client.
An idempotency key for the submission and a place to retain task identifiers.

Endpoints and authentication#

Send requests to https://api.runtoken.net with Authorization: Bearer YOUR_PLATFORM_KEY, replacing YOUR_PLATFORM_KEY with a platform API key created in the console.

Create a task: POST /v1/video/generations, with a JSON object as the request body.
Query a task: GET /v1/video/generations/{task_id}, using the native task ID from the submission response.

The following headers control submission and task lookup.

Header	When to send it	Purpose
`Content-Type: application/json`	When creating a task	Identifies the JSON request body.
`Idempotency-Key`	Required when creating a task	Identifies the submission; its value must be 8 to 128 characters long.
`X-Video-Task-Ref`	When a native task ID is ambiguous during lookup	Supplies the platform task reference to distinguish the task.

The native task ID and the platform task reference serve different purposes. Keep both when they are available; do not substitute the platform reference into the {task_id} path.

Create a task#

Prepare a local JSON file using the selected model's request format from the native examples below. The command below sends that file without imposing a provider-specific body structure.

Submit a video taskbash

curl -i 'https://api.runtoken.net/v1/video/generations' \
  -H 'Authorization: Bearer YOUR_PLATFORM_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \
  --data-binary '@YOUR_VIDEO_REQUEST.json'

Replace these values before running the command.

Example placeholder	Replace with
`YOUR_PLATFORM_KEY`	Your platform API key.
`YOUR_IDEMPOTENCY_KEY`	An 8 to 128 character key identifying this submission. Keep it for any retry of the same submission.
`YOUR_VIDEO_REQUEST.json`	The local JSON file containing the selected model's native request body.

In request formats that select the model through a model field, use the platform catalogue ID as its value. Keep prompts, reference inputs, duration, resolution and other fields in the format required by that model. Do not copy parameter names or enum values between model families.

curl reads the file after @; --data-binary sends its contents as the request body. The -i option displays response headers as well as the body, so you can retain the task reference if it is returned in a header.

Save the submission response, native task ID, available platform task reference, idempotency key and submitted JSON together. Use the selected model's response contract to locate the identifiers; the gateway does not define one shared JSON field for every provider.

Supported families and native request examples#

Runtoken supports asynchronous video integrations for Seedance, MiniMax Hailuo, Alibaba Wan and Kling. These families use different native request structures. Choose an available model version from the platform catalogue before using an example.

The following examples illustrate request shapes, not a shared set of defaults. Duration, resolution, audio and mode options depend on the selected model version and its platform configuration.

ByteDance Seedance#

Seedance uses the native contents/generations/tasks asynchronous protocol. Put the text prompt in a text item inside content.

Seedance request bodyjson

{
  "model": "YOUR_MODEL_ID",
  "content": [
    {
      "type": "text",
      "text": "A cinematic shot of a train crossing a mountain bridge"
    }
  ],
  "generate_audio": true
}

Replace YOUR_MODEL_ID with the platform model ID. For this request format, save the JSON as YOUR_VIDEO_REQUEST.json and submit it with the creation command above.

Field	Example value or structure	Meaning
`model`	`YOUR_MODEL_ID`	Platform model ID.
`content`	An array containing a `text` item	Native prompt content.
`generate_audio`	`true`	Requests audio in this example; availability depends on the model.

When resolving billing conditions, the platform treats Seedance audio as enabled if generate_audio is omitted. It does not insert the field into the request body, so this billing behavior is not a promise about the model's generation default.

Editing or derived tasks, callbacks, non-empty tools and draft are not supported. Audio and resolution options must match the configured platform pricing conditions.

MiniMax Hailuo#

Hailuo uses MiniMax's asynchronous video_generation protocol. The following shape places the prompt and generation options at the top level.

Hailuo request bodyjson

{
  "model": "YOUR_MODEL_ID",
  "prompt": "A cinematic shot of a train crossing a mountain bridge",
  "duration": 6,
  "resolution": "1080P"
}

Replace YOUR_MODEL_ID with the platform model ID and save the body as YOUR_VIDEO_REQUEST.json for the creation command above.

Field	Example value	Meaning
`prompt`	Text describing the scene	Content to generate.
`duration`	`6`	Example duration in seconds, not a default or a list of supported durations.
`resolution`	`1080P`	Example resolution; accepted values depend on the model version.

Some versions require a first-frame image or different resolution values. Use the fields required by your selected version rather than treating this text-only shape as valid for every Hailuo model.

Applicable billing rules require verifiable duration and input-image evidence from the completed result. Support in a billing policy does not establish the model's input-image limit or an included allowance.

Alibaba Wan#

Wan uses Bailian's asynchronous video-synthesis protocol. Its request separates input content from generation parameters.

Wan request bodyjson

{
  "model": "YOUR_MODEL_ID",
  "input": {
    "prompt": "A cinematic shot of a train crossing a mountain bridge"
  },
  "parameters": {
    "size": "1280*720",
    "duration": 5
  }
}

Replace YOUR_MODEL_ID with the platform model ID and save the body as YOUR_VIDEO_REQUEST.json for the creation command above.

Field	Example value or structure	Meaning
`input.prompt`	Text describing the scene	Native text input.
`parameters.size`	`1280*720`	Example size; some model versions use a different format or a `resolution` field.
`parameters.duration`	`5`	Example duration in seconds; supported values depend on the model.

The gateway sets X-DashScope-Async: enable on its upstream request automatically. You do not need to add that upstream header to the gateway submission example.

Completed-result usage evidence includes video count and input/output video durations. The platform's Wan background polling interval is at least 15 seconds; this is not a universal client-side query interval.

Kling#

The current Kling integration supports text-to-video. Its native body uses a provider model name rather than the platform model field shown in the other examples.

Kling native body structurejson

{
  "model_name": "YOUR_UPSTREAM_MODEL_NAME",
  "prompt": "A cinematic shot of a train crossing a mountain bridge",
  "duration": "5",
  "aspect_ratio": "16:9",
  "mode": "std"
}

Replace YOUR_UPSTREAM_MODEL_NAME with the provider model name specified for the selected integration. This is distinct from the platform catalogue ID.

Field	Example value	Purpose
`model_name`	`YOUR_UPSTREAM_MODEL_NAME`	Provider model name, where required by that version.
`duration`	`"5"`	Example duration expressed as a string.
`aspect_ratio`	`16:9`	Example output aspect ratio.
`mode`	`std`	Example generation mode.

Kling requests also require X-Platform-Model: YOUR_MODEL_ID; replace YOUR_MODEL_ID with the platform model ID.

For Kling, use the model-specific submission address and routing configuration supplied for the selected integration; the JSON body alone is not a complete submission command. The X-Platform-Model header does not replace authentication or the idempotency key.

Input-video and video editing are not supported. Duration-based billing requires exactly one output video with a verifiable duration. Whether model_name, duration and mode apply depends on the provider version.

Query the task#

Use the native task ID returned by the submission response in the query path.

Query a video taskbash

curl 'https://api.runtoken.net/v1/video/generations/YOUR_NATIVE_TASK_ID' \
  -H 'Authorization: Bearer YOUR_PLATFORM_KEY'

Replace YOUR_NATIVE_TASK_ID with the returned native task ID and YOUR_PLATFORM_KEY with your platform API key.

If that ID is ambiguous, add the platform task reference to the same query.

Query with a platform task referencebash

curl 'https://api.runtoken.net/v1/video/generations/YOUR_NATIVE_TASK_ID' \
  -H 'Authorization: Bearer YOUR_PLATFORM_KEY' \
  -H 'X-Video-Task-Ref: YOUR_VIDEO_TASK_REF'

Replace YOUR_VIDEO_TASK_REF with the platform task reference saved at submission; the other placeholders have the same meaning as above.

Runtoken polls tasks in the background. Query responses preserve the provider's native JSON, so your client must read the selected model's status, error and output fields. An HTTP response alone does not establish whether generation has succeeded.

Keep task querying separate from task creation. Querying an existing task should not cause your application to submit it again.

Handle failures and retries#

First establish whether the failure happened during submission, while querying, or during generation. Each case calls for a different action.

Situation	What to do
A network error leaves submission outcome uncertain	Retry with the same JSON body and the same `Idempotency-Key`. Do not create a new key for the same submission.
A native task ID has already been returned	Keep querying that task rather than submitting another generation request.
A query request fails	Retain the task identifiers and investigate the query failure separately from generation.
The native task response reports generation failure	Read the model's error details before deciding whether to submit a new task.
A model-access, account-balance or task-limit check rejects the request	Address the reported condition before trying again.

A disconnected client does not establish that the task failed. In particular, do not convert a timeout into an automatic new submission with a fresh idempotency key.

Inputs and results#

Confirm the model version and supported generation mode before accepting user inputs. A text-to-video integration does not establish image-to-video or video-editing support.

Part of the integration	What to check for the selected model
Request body	Prompt structure, accepted reference inputs, required fields and model-selection method.
Generation options	Supported duration, resolution, aspect ratio and audio options.
Task response	Native task ID, status values, error details and output locations.
Result handling	How the returned result is retrieved and any documented availability period.

Read results from the native response format. Do not assume a shared field such as video_url, a universal status enumeration, or the same media limits across models.

Current limitations#

The current video API accepts JSON objects and uses asynchronous tasks. The following features are not enabled:

Streaming video generation, including requests with stream: true.
Callbacks.
Derived or continuation tasks.
Video tools.

The current Kling integration supports text-to-video only. This does not establish image-to-video, input-video or editing support for that integration.

Usage and billing#

Task acceptance is not evidence of completed generation or settled billing. Video billing requires verifiable usage evidence, and the applicable rules depend on the model and its configured platform pricing.

Check the platform catalogue for sale prices. Provider list prices and example duration or resolution values do not establish what Runtoken charges for a task. Platform checks still apply to model access, account balance, task limits and idempotency.

Next steps#

For shared gateway behavior, see the integration guide. For other media endpoints, see Images and Audio.

Was this page helpful?