Videos API¶

Generate videos from text prompts and reference images with Amazon 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.

At a glance¶

• Amazon Nova Reel and Luma Ray 2 — clips from 5 to 120 seconds depending on the model, from a prompt and an optional first-frame image, see Models.
• Five endpoints — create, list, retrieve, download and delete a job, in the OpenAI Videos API shape, see Endpoints.
• Video IDs stay valid across restarts — a job identifier carries the invocation it names, so retrieve, download and delete work from any instance behind a load balancer, see How video generation works.
• Rendered into your own S3 buckets — Amazon Bedrock writes the MP4 under the videos/ prefix of the regional bucket you configure, with no traffic to third-party endpoints, see How video generation works.
• No remix, edits, extensions or characters — Amazon Bedrock generates the video asset alone, so variant=thumbnail and variant=spritesheet are refused too, see Feature compatibility.
• model is required, and a running job cannot be deleted — this gateway has no default video model, and DELETE answers 400 while a job is in_progress, see Limits and behaviour to know.

curl -X POST "$BASE/v1/videos" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "luma.ray-v2:0",
    "prompt": "Closeup of a seashell on a sandy beach, gentle waves"
  }'

Endpoints¶

Feature compatibility¶

Models¶

Any video generation model available in your configured Amazon Bedrock regions can be used, for example:

Amazon Models¶

Luma AI Models¶

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 with route=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 ID.

Amazon Nova Reel requires a PNG or JPEG matching the video resolution (1280x720) and only supports reference images for 6-second videos.

How video generation works¶

1. POST /v1/videos starts an Amazon Bedrock asynchronous invocation in a region where the model is available and a regional S3 bucket is configured (AWS_S3_REGIONAL_BUCKETS).
2. Amazon Bedrock renders the video and writes the MP4 to that bucket under AWS_S3_VIDEOS_PREFIX (videos/ by default).
3. GET /v1/videos/{video_id} reads the job state directly from Amazon Bedrock; .../content streams the MP4 from S3; DELETE removes the stored objects.

Billing¶

AWS bills video generation per second of generated video. Billed seconds appear in usage logs and cost tracking as output_seconds, recorded when the job is started. Standard S3 storage costs apply to the stored videos until they are deleted.

Limits and behaviour to know¶

Deleting a job that is still running¶

DELETE /v1/videos/{video_id} answers 400 Video is still being processed while the job reports in_progress: an Amazon Bedrock asynchronous invocation cannot be cancelled. Poll the job until it reports completed or failed, then delete it.

Downloading the content of an unfinished job returns 404 instead, matching upstream.

Retention¶

By default videos persist until deleted through the API. Set 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.

Request headers¶

The Amazon Bedrock guardrail headers apply to this endpoint. All headers are optional.

Content Safety (Guardrails)¶

The guardrail evaluates the prompt before the generation job is started; the generated video is not itself evaluated. Both headers are honoured only when AWS_BEDROCK_ALLOW_GUARDRAIL_OVERRIDE is enabled — otherwise the deployment's configured guardrail applies. X-Amzn-Bedrock-Trace is accepted but has no effect on this route — no guardrail trace is returned.

Example with headers:

curl -X POST "$BASE/v1/videos" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Amzn-Bedrock-GuardrailIdentifier: your-guardrail-id" \
  -H "X-Amzn-Bedrock-GuardrailVersion: 1" \
  -d '{
    "model": "luma.ray-v2:0",
    "prompt": "Closeup of a seashell on a sandy beach, gentle waves"
  }'

Try it¶

End to end with the OpenAI Python SDK:

import time

from openai import OpenAI

client = OpenAI(base_url="https://your-host/v1", api_key="your-api-key")

video = client.videos.create(
    model="luma.ray-v2:0", prompt="Closeup of a seashell on a sandy beach, gentle waves"
)
while video.status in ("queued", "in_progress"):
    time.sleep(10)
    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)

Create a job (curl):

curl -X POST "$BASE/v1/videos" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "luma.ray-v2:0",
    "prompt": "Closeup of a seashell on a sandy beach, gentle waves",
    "seconds": "5",
    "size": "1280x720"
  }'

Example response:

{
  "id": "video_eyJhcm4iOiJhcm46YXdzOmJlZHJvY2s6...",
  "object": "video",
  "model": "luma.ray-v2:0",
  "status": "queued",
  "progress": 0,
  "created_at": 1783805314,
  "seconds": "5",
  "size": "1280x720",
  "prompt": "Closeup of a seashell on a sandy beach, gentle waves"
}

Poll the job, then download the MP4:

VIDEO_ID="video_eyJhcm4iOiJhcm46YXdzOmJlZHJvY2s6..."

curl "$BASE/v1/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

curl "$BASE/v1/videos/$VIDEO_ID/content" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -o video.mp4

Next steps¶

Next: Models API · Files API · Images API · Storage configuration