---
title: "Create video"
method: POST
path: "/v1/videos"
---

# Create video

`POST /v1/videos`

Creates a new asynchronous video generation job using an OpenAI-compatible request format.

## Request body

- object
  - `model` string — The video generation model to use. Supports current Veo and Sora video models, including provider-prefixed variants like openai/sora-2 or google-vertex/veo-3.1-generate-preview.
  - `prompt` string, required — Text prompt describing the video to generate.
  - `size` string — Output resolution in OpenAI widthxheight format. Supported values depend on the selected model and provider mapping.
  - `callback_url` string, uri — LLMGateway extension. When set, a signed webhook is delivered after the job reaches a terminal state.
  - `callback_secret` string — LLMGateway extension. Shared secret used to sign webhook deliveries with HMAC-SHA256.
  - `input_reference` union — Reference image input alias. Accepts HTTPS URLs or base64 data URLs and routes to provider-specific image-guided video generation when supported.
    - string
    - object
      - `image_url` string, required
    - union[]
      - union — Input image for image-to-video generation. Supports HTTPS URLs and base64 data URLs. Routed to provider-specific image-to-video generation when supported by the selected model.
        - string
        - object
          - `image_url` string, required
  - `last_frame` union — Optional ending frame for frame-to-video generation. Requires image and is routed to providers that support first/last-frame generation.
    - string
    - object
      - `image_url` string, required
  - `seconds` integer, required — Output duration in seconds. Supported values depend on the selected model and provider mapping.
  - `audio` boolean — Whether the generated video should include audio. Support depends on the selected model and provider mapping.
  - `n` integer
  - `image` union — Input image for image-to-video generation. Supports HTTPS URLs and base64 data URLs. Routed to provider-specific image-to-video generation when supported by the selected model.
    - string
    - object
      - `image_url` string, required
  - `reference_images` union[] — Reference images for provider-specific asset or material-guided video generation. ByteDance Seedance 2.x models accept up to 9; other providers accept up to 3.
    - union — Input image for image-to-video generation. Supports HTTPS URLs and base64 data URLs. Routed to provider-specific image-to-video generation when supported by the selected model.
      - string
      - object
        - `image_url` string, required
  - `reference_videos` union[] — One to three reference videos (HTTPS URLs) for omni-reference video generation. Currently only supported on ByteDance Seedance 2.x models and can be combined with reference_images.
    - union — Reference video input for omni-reference video generation. Must be a publicly reachable HTTPS URL; base64 data URLs are not supported for videos.
      - string, uri
      - object
        - `video_url` string, uri, required
  - `reference_audios` union[] — One to three reference audio clips (HTTPS URLs) for omni-reference video generation. Currently only supported on ByteDance Seedance 2.x models and can be combined with reference_images and reference_videos.
    - union — Reference audio input for omni-reference video generation. Must be a publicly reachable HTTPS URL; base64 data URLs are not supported for audio.
      - string, uri
      - object
        - `audio_url` string, uri, required

## Response `200`

Video job created.

- object
  - `id` string, required
  - `object` 'video', required
  - `model` string, required
  - `status` 'queued' | 'in_progress' | 'completed' | 'failed' | 'canceled' | 'expired', required
  - `progress` integer, nullable, required
  - `created_at` number, required
  - `completed_at` number, nullable, required
  - `expires_at` number, nullable, required
  - `error` object, nullable, required
    - `code` string
    - `message` string, required
    - `details` unknown
  - `content` object[]
    - `type` 'video', required
    - `url` string, uri, required
    - `mime_type` string, nullable

## Other responses

- `400` — Invalid request body or parameters.
- `401` — Missing or invalid API key.
- `402` — Insufficient credits or plan limits reached.
- `403` — Forbidden request or upstream response.
- `404` — Unknown model or upstream not-found response.
- `410` — Archived or unavailable project.
- `429` — Rate limited (organization, endpoint, or upstream provider). Back off until Retry-After elapses.
- `500` — Internal server error.
- `502` — Failed to connect to the upstream provider.
- `503` — Service unavailable upstream response.
- `504` — Upstream provider timeout.

---

[API](https://skmtc.dev/llmgateway/apis/llmgateway-api.md) · [All operations](https://skmtc.dev/llmgateway/apis/llmgateway-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/llmgateway/llmgateway-api/revisions/aaf167e3d8cc/schema)