Token360
Sign Up

Submit video generation request

POST/v1/videos

Submit a normalized video generation request and create an asynchronous task. The API infers the generation workflow from frame_images and input_references roles. The response contains a video task id; poll that id with GET /v1/videos/{video_id} to check generation status and retrieve the final result.

To receive a webhook when the task reaches a terminal state, provide the optional callback_url field. See Webhook for delivery behavior, retries, and payload details.

Supported optional fields and allowed values are model-specific. Before sending optional parameters such as duration, resolution, size, aspect_ratio, generate_audio, service_tier, or provider policy fields, inspect GET /v1/models/{model_id} and use that model's parameter_schema and supported_parameters.

Authentication

Authorization Bearer

API key as bearer token in Authorization header.

Request Body

modelstringrequired

Model ID.

promptstringrequired

Video generation prompt.

durationinteger

Requested length of the generated video in seconds.

resolutionstring

Requested output video resolution or resolution tier.

sizestring

Requested output video size or resolution preset when the model uses a size field.

aspect_ratiostring

Requested output video frame shape as a width-to-height ratio.

generate_audioboolean

Controls whether video generation should include synthesized audio when supported.

prompt_extendboolean

Prompt extension flag.

watermarkboolean

Controls whether generated videos include a watermark when supported.

seedinteger

Optional numeric seed for repeatable generation when deterministic seeding is supported.

negative_promptstring

Negative prompt.

modestring

Generation mode.

cfg_scalenumber

Controls how strongly generation follows the prompt or guidance signal; higher values usually increase prompt adherence.

camera_controlobject

Camera control configuration.

camera_control.typestring

Camera control type.

camera_control.configobject

Camera control configuration.

camera_fixedboolean

Fixed camera flag.

callback_urlstring

Webhook callback URL.

external_task_idstring

External task ID.

character_orientationstring

Character orientation.

keep_original_soundboolean

Source-audio preservation flag.

qualitystring

Requested generation quality or fidelity tier.

fpsnumber

Requested output frame rate in frames per second.

sample_countinteger

Number of generated samples.

compression_qualitystring

Compression quality.

prompt_optimizerboolean

Prompt optimizer flag.

fast_pretreatmentboolean

Fast preprocessing flag.

return_last_frameboolean

Final-frame return flag.

movement_amplitudestring

Controls the amount of visual motion or camera/subject movement in the generated video when supported.

resize_modestring

Input resize mode.

person_generationstring

Person generation policy.

safety_identifierstring

Safety identifier.

draftboolean

Draft output flag.

request_idstring

Client request ID.

video_modestring

Video generation workflow.

service_tierstring

Service tier.

input_referencesarray

Reference media inputs.

input_references.typestringrequired

Reference media type, such as image_url, video_url, or audio_url.

input_references.image_urlobject

Image URL object for image references.

input_references.video_urlobject

Video URL object for video references.

input_references.audio_urlobject

Audio URL object for audio references.

input_references.rolestring

Reference role, such as reference, edit_source, or extend_source.

frame_imagesarray

Frame image inputs.

frame_images.typestringrequired

Frame media type, usually image_url.

frame_images.frame_typestringrequired

Frame role, such as first_frame or last_frame.

frame_images.image_urlobject

Image URL object for this frame.

bitrate_modestring

Requested bitrate or compression quality mode for generated video output.

metadataobject

Application metadata.

extra_bodyobject

Additional request body fields.

provider_optionsobject

Upstream configuration.

Response

idstring

Video task ID.

objectstring

Always video.

statusstring

Task status.

modelstring

Model used.

promptstring

Input prompt.

created_atinteger

Unix timestamp.

parametersobject

Normalized task parameters.

contentobject

Additional generated assets when returned.

content.last_frame_urlstring

Last-frame image URL when return_last_frame=true and returned.

responseobject

Raw response details when available.

errorobject

Error details when status=failed.

error.messagestring

Human-readable error message.

error.codestring

Machine-readable error code.

error.typestring

Error category when returned.

error.stagestring

Processing stage where the error occurred.

error.upstream_http_statusinteger

Provider HTTP status when the error came from upstream.

error.upstream_messagestring

Provider error message when available.

usageobject

Usage and billing details when available.

usage.prompt_tokensinteger

Input token count when returned.

usage.completion_tokensinteger

Output token count when returned.

usage.total_tokensinteger

Total token count when returned.

usage.input_tokensinteger

Input token count for providers that use input/output names.

usage.output_tokensinteger

Output token count for providers that use input/output names.

usage.generated_imagesinteger

Generated image count when returned.

usage.audio_duration_secondsnumber

Audio duration used for billing when returned.

usage.video_duration_secondsnumber

Video duration used for billing when returned.

usage.provider_request_idstring

Provider request ID used for upstream correlation.

Request

Shell
1curl -X POST https://api.token360.ai/v1/videos \
2  -H "Authorization: Bearer sk-your-api-key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model": "your-video-model",
6    "prompt": "A serene Japanese garden with cherry blossoms falling into a koi pond",
7    "resolution": "720p",
8    "duration": 8,
9    "aspect_ratio": "16:9",
10    "generate_audio": false,
11    "return_last_frame": false,
12    "execution_expires_after": 172800,
13    "safety_identifier": "user_123"
14  }'

Response

JSON
1{
2  "id": "your-video-id",
3  "object": "video",
4  "status": "queued",
5  "model": "your-video-model",
6  "prompt": "A serene Japanese garden with cherry blossoms falling into a koi pond",
7  "created_at": 1776351975,
8  "parameters": {
9    "resolution": "720p",
10    "duration": 8,
11    "aspect_ratio": "16:9",
12    "generate_audio": false,
13    "return_last_frame": false,
14    "execution_expires_after": 172800,
15    "safety_identifier": "user_123"
16  }
17}
Was this page helpful?