Videos
Create video
Start a text-to-video generation job
/v1/videosStart generating a video from a text prompt, optionally with a first and last frame or with reference images, videos or audio. The endpoint returns the job straight away with status: "queued". Generation takes minutes, so this response never contains the video. Poll Retrieve video until the job finishes, then download the MP4 from output.videos[0].url.
Send an Idempotency-Key header so a retry after a network error returns the original job while it is retained and has not been deleted. Generate the key once per video and store it before the first attempt. Use the same value for retries and after your program restarts. Deletion or automatic job removal releases the key, so a later create with it starts a new paid job. See retries and idempotency. Your account needs a payment method on file. See the Video generation guide for models, parameters, limits and billing.
Authorizationstringrequired
Your authentication credentials. For Basic authentication, populate Basic $INWORLD_API_KEY.
modelenum<string>required
The video model. Browse inworld.ai/models for model IDs, and see Model compatibility for each model's supported parameters.
Available options:alibaba/wan-3.0minimax/minimax-h3inworld/minimax-h3-fastinworld/minimax-h3-turboxai/grok-imagine-video-1.5-lite
promptstringrequired
What the video should show. The maximum length depends on the model; see Model compatibility.
secondsinteger
Clip length in whole seconds. The allowed range and the default depend on the model; see Model compatibility.
resolutionstring
Output resolution, case-insensitive. The allowed values and the default depend on the model; see Model compatibility.
aspect_ratiostring
Frame shape. The allowed values and the default depend on the model; see Model compatibility. With frame_images, leave it out or set adaptive: the video takes its shape from the first frame.
frame_imagesobject[]
A first frame, and optionally a last frame, for the video. At most one of each. Not every model accepts a last frame. Cannot be combined with input_references. For each model's frame support, see Model compatibility.
Show child attributes
typeenum<string>required
Available options:image_url
image_urlobjectrequired
Show child attributes
urlstringrequired
An HTTPS URL on a public host, up to 4,096 bytes. Base64 data: URLs are rejected. The model provider downloads the image when generation starts; we recommend keeping a signed URL valid for at least an hour. The API doesn't check this, and a URL the provider can't use fails the job with generation_failed.
frame_typeenum<string>required
Where the image goes in the video. A last_frame needs a first_frame.
Available options:first_framelast_frame
input_referencesoneOf[]
Images, videos or audio clips that guide the video without fixing any frame. Each model sets how many of each type it accepts, and not every model accepts video or audio. Cannot be combined with frame_images. For each model's limits, see Model compatibility.
Show child attributes
typeenum<string>required
The kind of reference, which names the field to set.
Available options:image_urlvideo_urlaudio_url
image_urlobject
The image.
Show child attributes
urlstringrequired
An HTTPS URL on a public host, up to 4,096 bytes. Base64 data: URLs are rejected. The model provider downloads the image when generation starts; we recommend keeping a signed URL valid for at least an hour. The API doesn't check this, and a URL the provider can't use fails the job with generation_failed.
video_urlobject
The video. It must be an MP4 or MOV file of up to 100 MB; the API downloads it when you create the job.
Show child attributes
urlstringrequired
An HTTPS URL on a public host, up to 4,096 bytes.
audio_urlobject
The audio clip. It can be sent on its own, without an image or video reference.
Show child attributes
urlstringrequired
An HTTPS URL on a public host, up to 4,096 bytes.
idstringrequired
The job id.
objectenum<string>required
Available options:video
modelstringrequired
statusenum<string>required
queued: accepted; waiting for or being submitted for generation, so cancellation may already be unavailable. in_progress: generating. completed: generation succeeded; download available until expires_at. failed: see error. cancelled: cancelled before generation started. The last three are terminal.
Available options:queuedin_progresscompletedfailedcancelled
created_atintegerrequired
When the job was created, in Unix seconds.
completed_atinteger
When the video finished, in Unix seconds. Present once status is completed.
expires_atinteger
Until when the video can be downloaded, in Unix seconds: 7 days after it finished. After it, the job is no longer listed. Present only when status is completed.
secondsintegerrequired
The requested clip length, with the model's default filled in.
resolutionstringrequired
The requested resolution, with the model's default filled in.
aspect_ratiostringrequired
The requested aspect ratio, with the model's default filled in. adaptive for a job with frame_images, whose video takes the first frame's shape.
operationstring
The job's long-running operation. Poll it with GET https://api.inworld.ai/lro/v1alpha/{operation} as an alternative to retrieving the job. The operation reports progress and the outcome but never the download link. See Poll the operation instead.
errorobject
Why the job failed. Present only when status is failed.
Show child attributes
codeenum<string>
content_filtered: the prompt or the generated video was blocked by the model provider's content policy. invalid_request: the model provider rejected the request. generation_failed: generation failed for another reason. generation_timeout: generation did not finish in time.
Available options:content_filteredinvalid_requestgeneration_failedgeneration_timeout
messagestring
outputobject
The finished video. Returned only by Retrieve video, only while status is completed and before expires_at.
Show child attributes
videosobject[]
Show child attributes
indexinteger
content_typestring
bytesinteger
File size in bytes.
urlstring
A signed HTTPS link to the MP4. Anyone with the link can download the file until url_expires_at, so treat it like a secret.
url_expires_atinteger
When url stops working, in Unix seconds: up to an hour after the request, and never after the job's expires_at.