Skip to main content
POST
/
openai
/
v1
/
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"
  }'

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

​
Request body

You can include additional parameters not listed here. They will be passed through to the underlying provider.
Each parameter has a badge showing how Lumenfall handles it across different providers:
BadgeMeaning
PassthroughPassed as-is; some providers may ignore it
RenamedField name is mapped to the provider’s expected name
ConvertedValue is transformed to match each provider’s format
EmulatedWorks consistently on all models, even if the provider doesn’t natively support it
Learn more about unified model behavior.
​
prompt
string
required
A text description of the desired video. Maximum length varies by model.Renamed
​
model
string
required
The model to use for video generation. See Models.
​
seconds
string or number
Duration of the video in seconds. Also accepted as duration.Converted
​
size
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
​
n
integer
default:"1"
The number of videos to generate. Must be between 1 and 4.Emulated
​
aspect_ratio
string
Aspect ratio for the video (e.g., 16:9, 9:16, 1:1). Lumenfall extension - converted to the provider’s native format.Converted
​
resolution
string
Video resolution shorthand: 720p, 1080p. Converted to appropriate dimensions per provider.Converted
​
input_reference
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
​
negative_prompt
string
Text describing what to avoid in the video. Maximum 5000 characters.Renamed
​
media_retention
string
How long to retain generated media. See Media retention.
​
webhook_url
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.
​
idempotency_key
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.
​
metadata
object
Key-value pairs of strings to attach to the video object.
​
user
string
A unique identifier representing your end-user. Only used by some providers.Passthrough

​
Query parameters

​
dryRun
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.
​
id
string
Unique identifier for the video.
​
object
string
Always "video".
​
created_at
integer
Unix timestamp of when the video was created.
​
status
string
The generation status. One of queued, in_progress, completed, or failed.
​
model
string
The model used for generation.
​
seconds
string
The requested duration.
​
size
string
Output dimensions as "WIDTHxHEIGHT" (e.g., "1920x1080") or aspect ratio (e.g., "16:9").
​
metadata
object
Metadata about the request execution, including cost estimates. See Billing.
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"
  }'

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