---
title: "Submit a video generation request"
method: POST
path: "/videos"
tags: ["Video Generation"]
---

# Submit a video generation request

`POST /videos`

Submits a video generation request and returns a polling URL to check status

## Request body

- VideoGenerationRequest
  - `aspect_ratio` '16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '3:2' | '2:3' | '21:9' | '9:21' — Aspect ratio of the generated video
  - `callback_url` string, uri — URL to receive a webhook notification when the video generation job completes. Overrides the workspace-level default callback URL if set. Must be HTTPS.
  - `creativity` integer — Creativity level for video upscaling models only. This parameter is not supported by video generation models.
  - `duration` integer — Duration of the generated video in seconds
  - `frame_images` FrameImage[] — Images to use as the first and/or last frame of the generated video. Each image must specify a frame_type of first_frame or last_frame.
    - `image_url` object, required
      - `url` string, required
    - `type` 'image_url', required
    - `frame_type` 'first_frame' | 'last_frame', required — Whether this image represents the first or last frame of the video
  - `generate_audio` boolean — Whether to generate audio alongside the video. Defaults to the endpoint's generate_audio capability flag, false if not set.
  - `input_references` InputReference[] — Reference assets to guide video generation. Accepts image, audio, and video references. Audio and video references are only honored by providers that support them (including BytePlus Seedance generation 2 and newer); other providers use image references and ignore the rest.
    - union — A reference asset used to guide video generation. Image references are supported by all providers; audio and video references are only honored by providers that support them (including BytePlus Seedance generation 2 and newer).
      - ContentPartImage
        - `image_url` object, required
          - `url` string, required
        - `type` 'image_url', required
      - ContentPartAudio
        - `audio_url` object, required
          - `url` string, required
        - `type` 'audio_url', required
      - ContentPartVideo
        - `type` 'video_url', required
        - `video_url` object, required
          - `url` string, required
  - `model` string, required
  - `previous_job_id` string — ID of a completed video job to edit or extend, as returned by the submit response. The new job runs on the same model and endpoint that produced the previous one. Only models that support continuation accept this field.
  - `prompt` string — Text prompt describing the video to generate. Optional for models that support generating a video from image input alone; required by all other models.
  - `provider` object — Provider-specific passthrough configuration
    - `options` object — Provider-specific options keyed by provider slug. Only options for the matched provider are forwarded; the rest are ignored. Unrecognized keys are silently dropped.
      - `01ai` object
      - `ai21` object
      - `aion-labs` object
      - `akashml` object
      - `alibaba` object
      - `amazon-bedrock` object
      - `amazon-bedrock/claude-on-aws` object
      - `amazon-nova` object
      - `ambient` object
      - `anthropic` object
      - `anthropic/2` object
      - `anyscale` object
      - `arcee-ai` object
      - `assemblyai` object
      - `atlas-cloud` object
      - `atoma` object
      - `avian` object
      - `azure` object
      - `baidu` object
      - `baseten` object
      - `black-forest-labs` object
      - `byteplus` object
      - `centml` object
      - `cerebras` object
      - `chutes` object
      - `cirrascale` object
      - `clarifai` object
      - `claude-on-aws` object
      - `cloudflare` object
      - `cohere` object
      - `coreweave` object
      - `cosine` object
      - `crofai` object
      - `crucible` object
      - `crusoe` object
      - `darkbloom` object
      - `databricks` object
      - `decart` object
      - `deepgram` object
      - `deepinfra` object
      - `deepseek` object
      - `dekallm` object
      - `digitalocean` object
      - `enfer` object
      - `fake-provider` object
      - `featherless` object
      - `fireworks` object
      - `fish-audio` object
      - `friendli` object
      - `gmicloud` object
      - `google-ai-studio` object
      - `google-vertex` object
      - `gopomelo` object
      - `groq` object
      - `heygen` object
      - `huggingface` object
      - `hyperbolic` object
      - `hyperbolic-quantized` object
      - `inception` object
      - `inceptron` object
      - `inferact-vllm` object
      - `inference-net` object
      - `infermatic` object
      - `inflection` object
      - `inocloud` object
      - `io-net` object
      - `ionstream` object
      - `klusterai` object
      - `krea` object
      - `lambda` object
      - `lepton` object
      - `liquid` object
      - `lynn` object
      - `lynn-private` object
      - `makora` object
      - `mancer` object
      - `mancer-old` object
      - `mara` object
      - `meta` object
      - `minimax` object
      - `mistral` object
      - `modal` object
      - `modelrun` object
      - `modular` object
      - `moonshotai` object
      - `morph` object
      - `ncompass` object
      - `near-ai` object
      - `nebius` object
      - `nex-agi` object
      - `nextbit` object
      - `nineteen` object
      - `novita` object
      - `nvidia` object
      - `octoai` object
      - `ollama` object
      - `open-inference` object
      - `openai` object
      - `parasail` object
      - `perceptron` object
      - `perplexity` object
      - `phala` object
      - `poolside` object
      - `primeintellect` object
      - `quiver` object
      - `recraft` object
      - `recursal` object
      - `reflection` object
      - `reka` object
      - `relace` object
      - `replicate` object
      - `runway` object
      - `sail-research` object
      - `sakana` object
      - `sakana-ai` object
      - `sambanova` object
      - `sambanova-cloaked` object
      - `seed` object
      - `sf-compute` object
      - `siliconflow` object
      - `sourceful` object
      - `stealth` object
      - `stepfun` object
      - `streamlake` object
      - `switchpoint` object
      - `targon` object
      - `tencent` object
      - `tenstorrent` object
      - `thinkingmachines` object
      - `together` object
      - `together-lite` object
      - `typesafe` object
      - `ubicloud` object
      - `unbiased` object
      - `upstage` object
      - `venice` object
      - `voyageai` object
      - `wafer` object
      - `wandb` object
      - `wandb-legacy` object
      - `xai` object
      - `xiaomi` object
      - `z-ai` object
  - `resolution` '480p' | '720p' | '768p' | '1080p' | '1K' | '2K' | '4K' — Resolution of the generated video
  - `seed` integer — If specified, the generation will sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed for all providers.
  - `session_id` string — A unique identifier for grouping related requests (e.g., a conversation or agent workflow). Used for observability grouping in Broadcast and private logging; never sent to the provider. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters.
  - `size` string — Exact pixel dimensions of the generated video in "WIDTHxHEIGHT" format (e.g. "1280x720"). Interchangeable with resolution + aspect_ratio.
  - `trace` TraceConfig — Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations.
    - `generation_name` string
    - `parent_span_id` string
    - `span_name` string
    - `trace_id` string
    - `trace_name` string
  - `upscale_factor` number — Upscale factor for video upscaling models only. This parameter is not supported by video generation models.
  - `user` string — A unique identifier representing your end-user. Forwarded to Broadcast and private logging as the end-user id; never sent to the provider.

## Response `202`

Video generation request accepted

- VideoGenerationResponse
  - `error` string
  - `generation_id` string — The generation ID associated with this video generation job. Available once the job has been processed.
  - `id` string, required — The video job ID, in the `gen-vid-<timestamp>-<20 alphanumerics>` generation ID format. Pass it as `previous_job_id` to continue the generation.
  - `polling_url` string, required
  - `status` 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'expired', required
  - `unsigned_urls` string[]
  - `usage` VideoGenerationUsage — Usage and cost information for the video generation. Available once the job has completed.
    - `cost` number, double, nullable — The cost of the video generation in USD.
    - `is_byok` boolean — Whether the request was made using a Bring Your Own Key configuration.

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed input
- `401` — Unauthorized - Authentication required or invalid credentials
- `402` — Payment Required - Insufficient credits or quota to complete request
- `403` — Forbidden - Authentication successful but insufficient permissions
- `404` — Not Found - Resource does not exist
- `413` — Payload Too Large - Request payload exceeds size limits
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - Unexpected server error

## Changes

- **2026-09-17** `3066544509b5` — 1 info
  - added the new optional request property `provider/options/allOf[#/components/schemas/ProviderOptions]/unbiased`
- **2026-09-17** `9a10bf686766` — 1 info
  - added the new optional request property `previous_job_id`
- **2026-09-17** `2de027b6dfcd` — 1 info
  - added the new optional request property `provider/options/allOf[#/components/schemas/ProviderOptions]/typesafe`
- **2026-09-16** `98e12733cd62` — 1 info
  - added the new optional request property `session_id`
- **2026-09-15** `81e9c582ae1c` — 1 info
  - added the new optional request property `trace`

[Full history](https://skmtc.dev/openrouterteam/apis/openrouter-api/changes/videos/post.md)

---

[API](https://skmtc.dev/openrouterteam/apis/openrouter-api.md) · [All operations](https://skmtc.dev/openrouterteam/apis/openrouter-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openrouterteam/apis/openrouter-api/revisions/dc4ac69fb923?raw)