---
title: "Generate a video"
method: POST
path: "/video"
tags: ["Videos"]
---

# Generate a video

`POST /video`

## Request

- Base URL: `https://api.wondercraft.ai/v1`
- URL: `https://api.wondercraft.ai/v1/video`
- Auth: API key in header `X-API-KEY`
- TypeScript: <https://skmtc.dev/wondercraft/apis/wondercraft-public-api/docs/video/post.ts> (a function with typed inputs; its response is checked against the schema)

Starts a background job that generates a video. The mode follows from the inputs you send:
nothing extra for text-to-video, `start_frame_image_id` for image-to-video (plus
`end_frame_image_id` for first/last frame), `reference_image_ids` and/or `reference_video_ids`
for references, or `source_video_id` to edit a video. The response contains a `job_id` to poll
with `GET /video/{job_id}`, and the credits the job is expected to cost.
Requires a valid `X-API-KEY` header.

Throws:
- 400 if the model, mode, resolution, duration or aspect ratio is not supported, a clip is too
  short or long, or the prompt references inputs the request does not carry
- 402 if the workspace does not have enough credits, or the model is not available on its plan
- 404 if an image or video does not exist or is not accessible
- 422 if the request body is invalid, e.g. it mixes inputs from different modes

## Request body

- GenerateVideoApiRequest
  - `prompt` string, required: What to generate. Refer to references as `@Image 1` or `@Video 1`.
  - `model_id` string, required: A model `id` from `GET /video/models`
  - `resolution` '480p' | '720p' | '1080p' | '2k' | '4k': Output resolution shared by the image and video APIs; each model lists the values it supports.
  - `aspect_ratio` '16:9' | '9:16' | '1:1'
  - `duration` integer, nullable: Seconds, one of the model's `durations`; defaults to its `default_duration`
  - `start_frame_image_id` string, uuid, nullable: Image to open the video with (image mode), from `POST /image/upload` or an image job
  - `end_frame_image_id` string, uuid, nullable: Image to end the video with (frames mode); requires `start_frame_image_id`
  - `reference_image_ids` string[]: Subject or style reference images (references mode), in prompt order
  - `reference_video_ids` string[]: Motion or style reference clips (references mode), in prompt order
  - `source_video_id` string, uuid, nullable: Video to edit (video_to_video mode), from `POST /video/upload` or a video job

## Response `200`

Successful Response

- CreateVideoJobResponse
  - `job_id` string, uuid, required: Poll `GET /video/{job_id}` with this ID
  - `estimated_credits` number, required: Credits this job is expected to cost once the video is ready

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-16** `200f24d7f14b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/wondercraft/apis/wondercraft-public-api/changes/video/post.md)

---

[API](https://skmtc.dev/wondercraft/apis/wondercraft-public-api.md) - [All operations](https://skmtc.dev/wondercraft/apis/wondercraft-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/wondercraft/apis/wondercraft-public-api/revisions/200f24d7f14b?raw)