--- title: Videos API - AWS Bedrock Video Generation (OpenAI Compatible) description: Generate videos from text prompts and reference images with AWS Bedrock video models using an OpenAI-compatible Videos API. Amazon Nova Reel and Luma Ray 2 through the Sora API shape. keywords: video generation API, text to video AWS, OpenAI videos API, Sora compatible, Amazon Nova Reel, Luma Ray, image to video, AWS Bedrock video --- # Videos API (OpenAI Compatible) Generate videos from text prompts and reference images with AWS Bedrock video models through the OpenAI Videos API shape. Video generation is **asynchronous**: creating a video returns a job object immediately. Poll the job until its status is `completed`, then download the MP4 content — exactly like the OpenAI (Sora) workflow, so the official OpenAI SDKs work unchanged. ## Why Choose the Videos API?
- :material-movie-open: __Text-to-Video & Image-to-Video__
Generate studio-quality clips from a prompt, optionally guided by a reference image used as the first frame. - :material-swap-horizontal: __Drop-in OpenAI Compatibility__
Follows the OpenAI Videos API shape. `client.videos.create(...)` works by changing the base URL. - :material-server-off: __Stateless by Design__
The video ID encodes the AWS Bedrock job reference — no database or server-side session, jobs survive server restarts and scale horizontally. - :material-cloud-lock: __Private AWS Backend__
Videos are generated by AWS Bedrock and stored in your own S3 buckets — no traffic to third-party endpoints.
## Quick Start: Available Endpoints | Endpoint | Method | What It Does | Powered By | MCP Tool | |--------------------------------|--------|--------------------------------------------------|--------------------------|--------------------------| | `/v1/videos` | POST | Start an asynchronous video generation job | AWS Bedrock Video Models | `openai_video_generation` | | `/v1/videos` | GET | List video generation jobs across regions | AWS Bedrock | `openai_video_list` | | `/v1/videos/{video_id}` | GET | Retrieve the current state of a job | AWS Bedrock | `openai_video_get` | | `/v1/videos/{video_id}/content`| GET | Download the generated MP4 once completed | Amazon S3 | `openai_video_content` | | `/v1/videos/{video_id}` | DELETE | Delete the stored video output | Amazon S3 | `openai_video_delete` | **Example with the OpenAI Python SDK:** ```python from openai import OpenAI client = OpenAI(base_url="https://your-host/v1", api_key="your-api-key") video = client.videos.create( model="amazon.nova-reel-v1:1", prompt="Closeup of a seashell on a sandy beach, gentle waves", ) while video.status in ("queued", "in_progress"): video = client.videos.retrieve(video.id) with open("video.mp4", "wb") as file: file.write(client.videos.download_content(video.id).read()) client.videos.delete(video.id) ``` **Example request (curl):** ```bash curl -X POST "https://your-host/v1/videos" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "amazon.nova-reel-v1:1", "prompt": "Closeup of a seashell on a sandy beach, gentle waves", "seconds": "6", "size": "1280x720" }' ``` **Example response:** ```json { "id": "video_eyJhcm4iOiJhcm46YXdzOmJlZHJvY2s6...", "object": "video", "model": "amazon.nova-reel-v1:1", "status": "queued", "progress": 0, "created_at": 1783805314, "seconds": "6", "size": "1280x720", "prompt": "Closeup of a seashell on a sandy beach, gentle waves" } ``` ## Model Support Any video generation model available in your configured AWS Bedrock regions can be used, for example: ### ![Amazon Nova](styles/logo_amazon_nova.svg){ style="height: 1.2em; vertical-align: text-bottom;" } Amazon Models | Model | Model ID | Durations (`seconds`) | Sizes (`size`) | |----------------------|-------------------------|------------------------------------|----------------| | Amazon Nova Reel 1.1 | `amazon.nova-reel-v1:1` | `6`, or multiples of 6 up to `120` | `1280x720` | | Amazon Nova Reel 1.0 | `amazon.nova-reel-v1:0` | `6` | `1280x720` | !!! note "Amazon Nova Reel is marked legacy by AWS" AWS flags the Nova Reel models as legacy, so they are hidden by default. Set [`AWS_BEDROCK_LEGACY=true`](operations_configuration.md#bedrock-legacy) to expose and use them. ### ![Luma AI](styles/logo_luma.svg){ style="height: 1.2em; vertical-align: text-bottom;" } Luma AI Models | Model | Model ID | Durations (`seconds`) | Sizes (`size`) | |------------|-----------------|-----------------------|-----------------------------------------------------------------------------------------------------| | Luma Ray 2 | `luma.ray-v2:0` | `5` or `9` | 540p/720p in ratios 1:1, 16:9, 9:16, 4:3, 3:4, 21:9, 9:21 (e.g. `1280x720`, `720x1280`, `960x540`) | When `seconds` or `size` is omitted, the model's shortest duration and default resolution are used. For Luma Ray, the requested size selects the model's resolution (smaller dimension: 540 or 720) and aspect ratio (reduced width:height). **Find compatible models:** Call [`/search_models`](api_search_models.md) with `mcp_tool=openai_video_generation` to discover model IDs that support video generation in your deployment. ## Reference Images (Image-to-Video) The optional `input_reference` image is used as the video's first frame: - **`multipart/form-data`** — upload the image file directly (this is what the OpenAI SDKs send). The SDK object form (`input_reference={"image_url": ...}` or `{"file_id": ...}`) is also accepted. - **`application/json`** — pass a base64 string, data URI, HTTPS URL, S3 URI, or [Files API](api_openai_files.md) ID. Amazon Nova Reel requires a PNG or JPEG matching the video resolution (1280x720) and only supports reference images for 6-second videos. ## Feature Compatibility
| Feature | Status | Notes | |-----------------------------|:----------------------------------------:|------------------------------------------------------------------------| | **Creation** | | | | `prompt` | :material-check-circle:{ .success } | Full support | | `model` | :material-minus-circle:{ .partial } | Required — this gateway has no implicit default video model | | `seconds` / `size` | :material-cog:{ .model-dep } | Supported values depend on the model (see table above) | | `input_reference` | :material-check-circle:{ .success } | First-frame image; also accepts URLs/S3/Files API IDs in JSON requests | | Extra model-specific params | :material-plus-circle:{ .extra-feature } | Extra fields are forwarded to the model (e.g. `seed`, `loop`) | | **Lifecycle** | | | | Retrieve / poll job | :material-check-circle:{ .success } | `progress` is `0` while running and `100` when completed | | Download content (`video`) | :material-check-circle:{ .success } | Streamed MP4 | | Delete video | :material-check-circle:{ .success } | Removes the stored output from S3 | | `variant=thumbnail/spritesheet` | :material-close-circle:{ .unsupported } | AWS Bedrock generates only the video asset | | List videos (`GET /v1/videos`) | :material-check-circle:{ .success } | Merged across regions; listed while AWS retains the job record | | Remix video | :material-close-circle:{ .unsupported } | Not available on AWS Bedrock | | Edits / extensions / characters | :material-close-circle:{ .unsupported } | `/v1/videos/edits`, `/videos/extensions`, and `/videos/characters` are not available on AWS Bedrock | | `expires_at` | :material-cog:{ .model-dep } | Reported when a [retention period](operations_configuration.md#aws-s3-videos-expires-after) is configured |
**Legend:** * :material-check-circle:{ .success } **Supported** — Fully compatible with the OpenAI API * :material-cog:{ .model-dep } **Available on Select Models** — Check your model's capabilities * :material-minus-circle:{ .partial } **Partial** — Supported with limitations * :material-close-circle:{ .unsupported } **Unsupported** — Not available in this implementation * :material-plus-circle:{ .extra-feature } **Extra Feature** — Enhanced capability beyond the OpenAI API
!!! note "Stateless job tracking" The video ID encodes the AWS Bedrock async job reference, so any server instance can serve the retrieve/download/delete calls without shared state. Two consequences: the `prompt` is only echoed in the creation response (not when polling or listing), and a deleted video's job record remains visible until AWS expires it. Listing reads the AWS Bedrock async invocation records of every configured region, so it also needs no server state. If a region is unreachable, listing skips it (logging a request warning) and still returns the jobs from the healthy regions. ## How It Works 1. `POST /v1/videos` starts an [AWS Bedrock asynchronous invocation](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_StartAsyncInvoke.html) in a region where the model is available and a regional S3 bucket is configured ([`AWS_S3_REGIONAL_BUCKETS`](operations_configuration.md#aws-s3-regional-buckets)). 2. AWS Bedrock renders the video and writes the MP4 to that bucket under [`AWS_S3_VIDEOS_PREFIX`](operations_configuration.md#aws-s3-videos-prefix) (`videos/` by default). 3. `GET /v1/videos/{video_id}` reads the job state directly from AWS Bedrock; `.../content` streams the MP4 from S3; `DELETE` removes the stored objects. !!! warning "S3 bucket requirement" AWS Bedrock requires the output bucket to be **in the same region as the invocation**. Configure a bucket for each region offering video models via `AWS_S3_REGIONAL_BUCKETS`, otherwise video generation requests fail with a configuration error. ## Retention By default videos persist until deleted through the API. Set [`AWS_S3_VIDEOS_EXPIRES_AFTER`](operations_configuration.md#aws-s3-videos-expires-after) to enforce a retention period: the `Video` object then reports `expires_at` (completion time plus the retention period) and downloading expired content returns a 404, matching the OpenAI API's automatic video expiry. ## Billing AWS bills video generation per **second of generated video**. Billed seconds appear in [usage logs and cost tracking](operations_logging_monitoring.md) as `output_seconds`, recorded when the job is started. Standard S3 storage costs apply to the stored videos until they are deleted.