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?¶

Quick Start: Available Endpoints¶

Example with the OpenAI Python SDK:

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):

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:

{
  "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 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 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 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¶

How It Works¶

1. POST /v1/videos starts an AWS Bedrock asynchronous invocation in a region where the model is available and a regional S3 bucket is configured (AWS_S3_REGIONAL_BUCKETS).
2. AWS 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 AWS Bedrock; .../content streams the MP4 from S3; DELETE removes the stored objects.

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.

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.