{
    "schema_version": "1.0",
    "id": "operation:create-video",
    "canonical_url": "/docs/reference/create-video",
    "openapi_url": "/docs/openapi.json",
    "openapi_sha256": "e2df63aaf950718064b6fb363ad93d3a550007322b41a021543c8a2365b3fa91",
    "contract": {
        "summary": "Create Video",
        "tags": [
            "Videos"
        ],
        "description": "Starts a video render and answers `202` at once with the job; poll its `polling_url`, or pass `callback_url` to be notified. The request follows OpenRouter's video API, so the OpenRouter SDKs work by changing the base URL and key. OpenAI/Sora field names are accepted too: `seconds` for `duration`, `size`, and `input_reference` (an uploaded file in `multipart/form-data`, an https URL string, or `{image_url}`) for the first frame. `GET /v1/videos/models` lists the models with what each accepts.\n\n**Modes (minimax-h3):** text only; `frame_images` with a `first_frame`, a `last_frame` or both; or `input_references` (up to 9 images, 3 videos and 3 audio clips, 12 in all). When both `frame_images` and `input_references` are sent, `frame_images` is used.\n\n**Media:** an https URL or a base64 data URI. Images JPG, PNG, WEBP, HEIC or HEIF up to 30 MB; videos MP4 or MOV up to 50 MB, 2-15 s; audio WAV or MP3 up to 15 MB, 2-15 s.\n\n**Sizes (minimax-h3):** 4 to 15 seconds at 24 fps, with stereo AAC audio. Send `aspect_ratio` or `size`:\n\n| `aspect_ratio` | `size` |\n|---|---|\n| `16:9` (default) | `1344x768` |\n| `9:16` | `768x1344` |\n| `4:3` | `1024x768` |\n| `3:4` | `768x1024` |\n| `1:1` | `768x768` |\n| `21:9` | `1536x672` |\n\n**Output:** duration snaps to the model's frame grid, so a 4 s request is about 4.4 s; read `output.duration`. Videos have a generated soundtrack unless `generate_audio` is `false`.\n\n**Prompts** are used as written. MiniMax's and fal's APIs rewrite prompts by default, so the same prompt can give a different video here.\n\n**Expected wait:** while a job is `pending`, `queue_position` counts the jobs ahead of it for the same model. Once it starts, a minimax-h3 render takes about 3 seconds per second of video for text and frame jobs, and about 5 seconds per second with `input_references`: a 6 s text job is ready in about 20 s. At 2K a render takes about 3 times as long: a 15 s text job takes about 140 s. `progress` is estimated from these times.\n\n**Quality (minimax-h3):** `quality` picks a tier, the same in every mode. `turbo` (or `auto`, `low`; the default) uses H3's Turbo LoRA: 4 denoising steps, or 8 with `input_references`. `standard` (or `medium`) runs the full base model at 20 steps and bills 1.5 times the seconds; `max` (or `high`) runs 40 steps and bills 3 times; `ultra` runs 50 steps and bills 5 times. For finer control send `num_inference_steps` from 10 to 50 instead (OpenRouter's SDKs: `provider.options.stealth.quality` or `.num_inference_steps`); more steps take longer and cost more. Sending a tier and a different step count is a 400.\n\n**Billing:** per second of requested `duration` at the model's price (`pricing_skus` in `GET /v1/videos/models`; `standard_per_second`, `max_per_second` and `ultra_per_second` are the tiers' prices, `2K_per_second` the 2K price), only when the job completes. `standard` bills 1.5 times the seconds, `max` 3 times and `ultra` 5 times; `resolution: 2K` (Turbo only) 3 times. A raw `num_inference_steps` bills the tier whose step range holds it: 10 to 20 as `standard`, 21 to 40 as `max`, 41 to 50 as `ultra` (`quality_tiers[].step_range` in `GET /v1/videos/models`). Billed seconds are rounded up to a whole second: a 5 s job at `standard` bills 8 s. `usage.billed_seconds` shows the result. Failed and cancelled jobs are not billed.\n",
        "operationId": "create-video",
        "security": [
            {
                "APIKey": []
            }
        ],
        "requestBody": {
            "required": true,
            "content": {
                "application/json": {
                    "schema": {
                        "$ref": "#/components/schemas/create-video-request-payload"
                    },
                    "example": {
                        "model": "minimax-h3",
                        "prompt": "A red fox trots through fresh snow at dawn, breath steaming.",
                        "duration": 6,
                        "aspect_ratio": "16:9",
                        "callback_url": "https://example.com/hooks/video"
                    }
                },
                "multipart/form-data": {
                    "schema": {
                        "$ref": "#/components/schemas/create-video-multipart-request-payload"
                    }
                }
            }
        },
        "responses": {
            "202": {
                "description": "Accepted. The job, `pending`, with its `polling_url` and `queue_position`.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/video-job-payload"
                        }
                    }
                }
            },
            "400": {
                "description": "A field the model does not support or a malformed input. The message names the field. Fields are typed, not coerced; `prompt` must be a string, `generate_audio` a boolean (`true` or `false`), `input_reference` a URL string or an object - and a whole number may be sent as text (`\"20\"`).",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/error-payload"
                        }
                    }
                }
            },
            "401": {
                "$ref": "#/components/responses/unauthorized"
            },
            "404": {
                "description": "Unknown video model",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/error-payload"
                        }
                    }
                }
            },
            "503": {
                "description": "The model has no valid capability spec at the moment and is not served.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/error-payload"
                        }
                    }
                }
            },
            "413": {
                "description": "A media input is over its size limit",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/error-payload"
                        }
                    }
                }
            }
        }
    },
    "example_id": "example:operation/create-video",
    "operation_id": "create-video",
    "method": "POST",
    "path": "/v1/videos",
    "deprecated": false
}