Generate videos

curl -X POST https://api.lumenfall.ai/openai/v1/videos \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A capybara lounging in a hot spring, steam rising gently, slow camera pan",
    "seconds": 10,
    "size": "1920x1080"
  }'

curl -X POST https://api.lumenfall.ai/openai/v1/videos \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "The capybara turns its head and blinks slowly",
    "seconds": 5,
    "input_reference": {
      "image_url": "https://example.com/capybara.jpg"
    }
  }'

curl -X POST https://api.lumenfall.ai/openai/v1/videos \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -F model=sora-2 \
  -F prompt="The capybara turns its head and blinks slowly" \
  -F seconds=5 \
  -F input_reference=@capybara.jpg

from openai import OpenAI

client = OpenAI(
    api_key="your-lumenfall-api-key",
    base_url="https://api.lumenfall.ai/openai/v1"
)

# Text-to-video
video = client.videos.create(
    model="sora-2",
    prompt="A capybara lounging in a hot spring, steam rising gently, slow camera pan",
    seconds=10,
    size="1920x1080",
)

print(video.id)  # Use this ID to poll for status

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-lumenfall-api-key",
  baseURL: "https://api.lumenfall.ai/openai/v1",
});

// Text-to-video
const video = await client.videos.create({
  model: "sora-2",
  prompt:
    "A capybara lounging in a hot spring, steam rising gently, slow camera pan",
  seconds: 10,
  size: "1920x1080",
});

console.log(video.id); // Use this ID to poll for status

{
  "id": "video_abc123",
  "object": "video",
  "created_at": 1702345678,
  "status": "queued",
  "model": "sora-2",
  "seconds": "10",
  "size": "1920x1080",
  "metadata": {
    "model": "sora-2",
    "executed_model": "openai/sora-2",
    "provider": "openai",
    "provider_name": "OpenAI",
    "cost_estimate": 0.21,
    "cost_currency": "USD"
  }
}

POST

openai

videos

curl -X POST https://api.lumenfall.ai/openai/v1/videos \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A capybara lounging in a hot spring, steam rising gently, slow camera pan",
    "seconds": 10,
    "size": "1920x1080"
  }'

curl -X POST https://api.lumenfall.ai/openai/v1/videos \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "The capybara turns its head and blinks slowly",
    "seconds": 5,
    "input_reference": {
      "image_url": "https://example.com/capybara.jpg"
    }
  }'

curl -X POST https://api.lumenfall.ai/openai/v1/videos \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -F model=sora-2 \
  -F prompt="The capybara turns its head and blinks slowly" \
  -F seconds=5 \
  -F input_reference=@capybara.jpg

from openai import OpenAI

client = OpenAI(
    api_key="your-lumenfall-api-key",
    base_url="https://api.lumenfall.ai/openai/v1"
)

# Text-to-video
video = client.videos.create(
    model="sora-2",
    prompt="A capybara lounging in a hot spring, steam rising gently, slow camera pan",
    seconds=10,
    size="1920x1080",
)

print(video.id)  # Use this ID to poll for status

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-lumenfall-api-key",
  baseURL: "https://api.lumenfall.ai/openai/v1",
});

// Text-to-video
const video = await client.videos.create({
  model: "sora-2",
  prompt:
    "A capybara lounging in a hot spring, steam rising gently, slow camera pan",
  seconds: 10,
  size: "1920x1080",
});

console.log(video.id); // Use this ID to poll for status

{
  "id": "video_abc123",
  "object": "video",
  "created_at": 1702345678,
  "status": "queued",
  "model": "sora-2",
  "seconds": "10",
  "size": "1920x1080",
  "metadata": {
    "model": "sora-2",
    "executed_model": "openai/sora-2",
    "provider": "openai",
    "provider_name": "OpenAI",
    "cost_estimate": 0.21,
    "cost_currency": "USD"
  }
}

Generate videos from a text prompt or input image using AI models from various providers.

OpenAI compatibilityThis endpoint implements the OpenAI Videos API. You can use any OpenAI SDK by changing the base URL to https://api.lumenfall.ai/openai/v1.Lumenfall normalizes behavior across all models - mapping parameters, emulating features, and standardizing errors - so your code works consistently regardless of which provider handles the request.

Async workflowVideo generation is asynchronous. A successful request returns a 202 response with a video object in queued status. Poll GET /v1/videos/{id} until the status is completed or failed. You can also use webhooks to receive a notification when the video is ready.

Content typesThis endpoint accepts both application/json and multipart/form-data requests. Use multipart when you want to upload image files directly instead of passing URLs.

Record & Replay: this endpoint supports replaying recorded responses and instant mock responses. Set X-Lumenfall-Replay (and optionally X-Lumenfall-Replay-Match) to record, replay, or mock a call. See the Record & Replay guide.

Request body

You can include additional parameters not listed here. They will be passed through to the underlying provider.

What do the parameter badges mean?

Each parameter has a badge showing how Lumenfall handles it across different providers:

Badge	Meaning
Passthrough	Passed as-is; some providers may ignore it
Renamed	Field name is mapped to the provider’s expected name
Converted	Value is transformed to match each provider’s format
Emulated	Works consistently on all models, even if the provider doesn’t natively support it

Learn more about unified model behavior.

string

required

A text description of the desired video. Maximum length varies by model.Renamed

string

required

The model to use for video generation. See Models.

string or number

Duration of the video in seconds. Also accepted as duration.Converted

string

The dimensions of the generated video, as WIDTHxHEIGHT (e.g., 1920x1080) or aspect ratio (e.g., 16:9). Supported sizes vary by model.Converted

integer

default:"1"

The number of videos to generate. Must be between 1 and 4.Emulated

string

Aspect ratio for the video (e.g., 16:9, 9:16, 1:1). Lumenfall extension - converted to the provider’s native format.Converted

string

Video resolution shorthand: 720p, 1080p. Converted to appropriate dimensions per provider.Converted

object or array

Reference image(s) for image-to-video generation. Not all models support this - check the model’s capabilities.Accepts a single object or an array of objects:

// Single reference
{"image_url": "https://example.com/photo.jpg"}

// Multiple references
[{"image_url": "https://..."}, {"image_url": "https://..."}]

image_url can be an HTTPS URL or a base64 data URI. The number of references accepted depends on the model (most models support at most 1).When using multipart/form-data, send file uploads or URL strings as input_reference fields instead. Multiple files are supported via input_reference, input_reference[], or input_reference[N] field names.Renamed

string

Text describing what to avoid in the video. Maximum 5000 characters.Renamed

string

How long to retain generated media. See Media retention.

string

URL to receive a webhook notification when the video completes or fails. Deliveries are signed with your organization’s webhook secret - retrieve it via Get webhook secret. See Webhooks for payload format and verification.

string

A unique key (up to 256 characters) to prevent duplicate requests. If you send the same key twice, the second request returns the existing video instead of creating a new one.

object

Key-value pairs of strings to attach to the video object.

string

A unique identifier representing your end-user. Only used by some providers.Passthrough

Query parameters

boolean

default:"false"

If true, returns a cost estimate without generating the video. See Cost estimation.

Response

Returns a 202 Accepted response with the video object.

string

Unique identifier for the video.

string

Always "video".

integer

Unix timestamp of when the video was created.

string

The generation status. One of queued, in_progress, completed, or failed.

string

The model used for generation.

string

The requested duration.

string

Output dimensions as "WIDTHxHEIGHT" (e.g., "1920x1080") or aspect ratio (e.g., "16:9").

object

Metadata about the request execution, including cost estimates. See Billing.

Show Metadata object

string

Provider display name (e.g., "Google Vertex AI").

string

Provider slug (e.g., "replicate").

string

The provider’s job ID, useful for reconciliation.

string

The model string sent in the request.

string

The model that was actually executed, as "{provider_slug}/{provider_model}".

number

Final effective cost. Only present when the job is completed.

number

Estimated cost. Present while the job is queued or in_progress.

string

Currency of the cost (e.g., "USD").

Headers

Optional headers that enable Record & Replay. See the guide and Modes & matching for the full behavior matrix, response signals, and error codes.

string

Activation: record, replay-or-mock, replay-or-error, replay-or-live, replay-or-record, mock, or off. Omit (with no key default) to run normally.

string

default:"standard"

How recordings are matched: standard, strict, specific, or pinned.

string

Comma-separated fields to match on. Required for specific.

string

Recording ID to replay. Required for pinned.

string

default:"instant"

Latency simulation: instant, real, or {ttfb},{duration} in ms.

curl -X POST https://api.lumenfall.ai/openai/v1/videos \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A capybara lounging in a hot spring, steam rising gently, slow camera pan",
    "seconds": 10,
    "size": "1920x1080"
  }'

curl -X POST https://api.lumenfall.ai/openai/v1/videos \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "The capybara turns its head and blinks slowly",
    "seconds": 5,
    "input_reference": {
      "image_url": "https://example.com/capybara.jpg"
    }
  }'

curl -X POST https://api.lumenfall.ai/openai/v1/videos \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -F model=sora-2 \
  -F prompt="The capybara turns its head and blinks slowly" \
  -F seconds=5 \
  -F input_reference=@capybara.jpg

from openai import OpenAI

client = OpenAI(
    api_key="your-lumenfall-api-key",
    base_url="https://api.lumenfall.ai/openai/v1"
)

# Text-to-video
video = client.videos.create(
    model="sora-2",
    prompt="A capybara lounging in a hot spring, steam rising gently, slow camera pan",
    seconds=10,
    size="1920x1080",
)

print(video.id)  # Use this ID to poll for status

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-lumenfall-api-key",
  baseURL: "https://api.lumenfall.ai/openai/v1",
});

// Text-to-video
const video = await client.videos.create({
  model: "sora-2",
  prompt:
    "A capybara lounging in a hot spring, steam rising gently, slow camera pan",
  seconds: 10,
  size: "1920x1080",
});

console.log(video.id); // Use this ID to poll for status

{
  "id": "video_abc123",
  "object": "video",
  "created_at": 1702345678,
  "status": "queued",
  "model": "sora-2",
  "seconds": "10",
  "size": "1920x1080",
  "metadata": {
    "model": "sora-2",
    "executed_model": "openai/sora-2",
    "provider": "openai",
    "provider_name": "OpenAI",
    "cost_estimate": 0.21,
    "cost_currency": "USD"
  }
}

Overview

Images

Videos

Chat

Models

Webhooks

Billing

Request body

Query parameters

Response

Headers

​Request body

​Query parameters

​Response

​Headers

Request body

Query parameters

Response

Headers