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.

Why Choose the Videos API?¶

Quick Start: Available Endpoints¶

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

Example request (curl):

curl -X POST "https://your-host/v1/videos" \
  -H "Authorization: Bearer $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"
}

Feature Compatibility¶

Model Support¶

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 It 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.

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.

Ready to bring your ideas to motion? Explore available video models in the Models API.