Skip to main content
POST
Create Video Generation

Authorizations

Authorization
string
header
required

Enter your MeshAPI key (rsk_...) or, for the admin-keys endpoints, a dashboard session token — sent as Authorization: Bearer <token>.

Headers

X-Mesh-Version
enum<string>
default:2026-08

Dated version of the API contract to pin this request to. Omit it and the request is served under 2026-08 — the oldest supported version, so an existing integration is never moved by a release. A malformed or unsupported value is rejected with 400 invalid_api_version rather than falling back silently. The version actually served is echoed as X-Mesh-Version on every response, including errors.

Available options:
2026-08,
2026-09

Body

application/json
model
string
required

Which model generates the video. Use an id from GET /v1/models.

content
VideoContentItem · object[]
required

Your prompt, plus any images, video or audio the model should work from.

previous_task_id
string | null

Continue from one of your earlier finished videos instead of uploading it again.

callback_url
string | null

We POST the finished task here when the model supports callbacks; a model that does not is refused rather than silently never calling you. Delivery is best effort and is not retried, so keep polling as your fallback.

return_last_frame
boolean
default:false

Also return a still of the final frame, so you can chain it into the next clip.

service_tier
string | null

Pick a faster or cheaper processing tier, where the model offers one.

execution_expires_after
integer | null

Seconds before an unfinished task is given up on. Defaults to 48 hours.

generate_audio
boolean | null

Generate a soundtrack along with the picture.

draft
boolean | null

Generate a quick low-resolution preview instead of the finished video.

resolution
string | null

Output resolution, such as 720p or 1080p, or an exact size like 1280x720 on the models that take one.

ratio
string | null

Aspect ratio, such as 16:9 or 9:16. Use adaptive to follow your input.

duration
integer | null

How long the video should be, in seconds.

Required range: 1 <= x <= 300
match_source_duration
boolean | null

Make the video as long as the source video you sent, instead of a fixed length. Cannot be combined with duration.

fast_pretreatment
boolean | null

Skip some prompt pre-processing so generation starts sooner.

frames
integer | null

Exact number of frames, as an alternative to duration.

seed
integer | null

Reuse a seed to get a similar result again.

camera_fixed
boolean | null

Hold the camera still instead of letting it move.

watermark
boolean | null

Add the model's watermark to the output.

safety_identifier
string | null

A stable, anonymised id for the person making the request, used for abuse detection.

priority
integer | null

Nudge this task ahead of your other queued tasks.

Required range: 0 <= x <= 9
external_task_id
string | null

Your own id for this task, echoed back so you can match it to your records.

multi_shot
boolean | null

Let the model compose the video as several shots.

negative_prompt
string | null

What to keep out of the generated video.

guidance_scale
number | null

How closely to follow the prompt. Higher stays nearer your wording; lower gives the model more freedom.

Required range: 1 <= x <= 10
prompt_extend
boolean | null

Let the model expand your prompt with extra detail before it generates.

style
string | null

A named visual style, on models that offer them.

movement_amplitude
string | null

How much the subjects in frame are allowed to move.

bgm
boolean | null

Add background music to the generated video.

keep_original_sound
boolean | null

Keep the audio from your source video instead of generating new audio.

audio_type
string | null

Which kinds of sound to generate: speech, effects, or both.

output_format
string | null

Container for the returned file. The accepted values are the model's own and the value is passed through unchecked.

omni_reference_task_type
string | null

Say up front whether you are generating from references, editing a video, or extending one, so a mismatch is caught when you submit rather than failing later.

web_search
boolean | null

Let the model look up current details mentioned in your prompt.

bitrate_mode
string | null

Encode at a higher bitrate for a cleaner picture and a larger file.

num_inference_steps
integer | null

How many refinement steps to run. More can improve quality and takes longer.

Required range: 1 <= x <= 100
enable_safety_checker
boolean | null

Run the model's own content check on the result.

thinking_level
string | null

How much the model reasons about your prompt before it starts generating.

tags
Tags · object | null

Your own labels for this request, echoed back on the usage row and available as a filter and a group-by dimension in the usage API. String keys to string values. Never put personal or sensitive data here — tags are stored with the usage record and are not redacted.

Example:

Response

Task created; poll the returned id for status

The submit response, which carries one field retrieval cannot.

MESH-714. unsupported_params is the parameters the caller sent that the SERVED provider drops — knowable only at submit, and reconstructing it on a later read would mean persisting it per task. It is on a subclass rather than on VideoTaskResponse because that model is also what the poll and list paths return AND what upstream payloads are parsed into, so a field there would appear as a null on responses that can never populate it.

Null (not absent) when nothing was dropped, like every other optional field.

id
string
required
request_id
string | null
model
string | null
status
string
default:queued
error
VideoTaskError · object | null
created_at
integer | null
updated_at
integer | null
content
VideoTaskContent · object | null
seed
integer | null
resolution
string | null
ratio
string | null
duration
integer | null
frames
integer | null
framespersecond
integer | null
generate_audio
boolean | null
billed_seconds
number | null
billed_resolution
string | null
billed_usd
number | null
settled
boolean | null
safety_identifier
string | null
priority
integer | null
draft
boolean | null
draft_task_id
string | null
service_tier
string | null
execution_expires_after
integer | null
usage
VideoTaskUsage · object | null
unsupported_params
string[] | null
dropped_parameters
DroppedParameter · object[] | null