Skip to main content
POST
Create video
Requires workspace preview access. See Video and batch jobs for setup, webhooks, and result handling.

Authorizations

Authorization
string
header
required

Bearer token authentication

Body

application/json
model
string
required
prompt
string
required
duration
integer

Desired duration in seconds (provider/model dependent).

input_video_duration
number<double>

Duration of the source video in seconds. Required when a provider bills source-video duration independently from generated output.

Required range: 0 < x <= 3600
input_audio_duration
number<double>

Declared source-audio duration in seconds, used for provider range validation. Providers that do not report authoritative usage may bill at their supported input-duration ceiling.

Required range: 2 <= x <= 20
size
string

Explicit dimensions (for example 1280x720). Cannot be combined with resolution or aspect_ratio.

resolution
string

480p, 720p, 1080p, 1K, 2K, 4K. Can be combined with aspect_ratio. Cannot be combined with size.

aspect_ratio
string

Aspect ratio such as 16:9, 9:16, 1:1. Can be combined with resolution. Cannot be combined with size.

seed
integer
sample_count
integer
Required range: 1 <= x <= 4
negative_prompt
string
generate_audio
boolean
enhance_prompt
boolean
compression_quality
integer
person_generation
string
resize_mode
string
input_references
object[]

HTTPS image, audio, or video inputs used to condition generation. Supported types, roles, counts, and combinations depend on the selected model. Check GET /videos/models before submitting a job. The singular input_reference compatibility alias, omitted from this schema, accepts a multipart image or an object containing exactly one of file_id or image_url. Support depends on the provider.

A typed HTTPS media input. Use image_url for images and media_url for audio or video. Roles describe how the model should use the input; provider and model support varies.

frame_images
object[]

HTTPS first/last frame images. Each frame_type may appear once. Do not also supply input_reference or frame roles in input_references.

Required array length: 1 - 2 elements
provider_params
object

Provider-specific extensions only. Complete request passthrough and duplicate routing, prompt, callback, or billing fields are rejected.

provider_options
object

Extensions keyed by canonical provider ID (for example atlascloud or byteplus). Only the selected provider's options are forwarded. Cannot be combined with provider_params. Routing, prompt, callback, duration, resolution, and output-count fields must use validated top-level fields.

output
object
webhook
object
provider
object

Provider routing preferences for gateway selection.

Response

202 - application/json

Video response

id
string
polling_url
string
websocket_url
string<uri>

WebSocket URL for subscribing to normalized async job lifecycle updates.

model
string
request_id
string
session_id
string
status
enum<string>
Available options:
queued,
processing,
completed,
failed,
cancelled,
expired
lifecycle_status
enum<string>

Normalized async lifecycle status for polling, websocket, and webhook consumers.

Available options:
pending,
running,
completed,
failed,
cancelled,
expired
cancel_url
string<uri> | null

Reserved for compatibility; currently always null.

output_access
enum<string>
Available options:
bytes,
signed_url,
both
generation_id
string | null
native_video_id
string | null

Provider-native video/job id when it differs from the gateway-owned id.

created_at
started_at
completed_at
object
string
Example:

"video"

poll_after_seconds
integer
Example:

20

provider
string
seconds
number
size
string
audio
boolean
content_url
string

Present when output_access includes bytes (authenticated endpoint).

download_url
string | null

Signed first-party URL for direct download when status is completed.

expires_at
integer | null

Unix timestamp (seconds) when the signed download_url expires.

progress
integer | null
progress_source
string
asset
object | null
outputs
object[]
billing
object
webhook
object

Sanitized async webhook configuration plus delivery state. Secrets are never returned; has_secret indicates whether signed deliveries are enabled. Signed deliveries include x-phaseo-signature, x-phaseo-timestamp, x-phaseo-event-id, x-phaseo-event-type, x-phaseo-delivery-key, x-phaseo-attempt, and x-phaseo-max-attempts headers.

next_webhook_retry_at
string | null

ISO timestamp for the next scheduled user-webhook retry, when queued.

last_webhook_progress
number | null

Most recent coarse progress bucket dispatched to webhook consumers.

last_webhook_progress_at
string | null

ISO timestamp when the most recent webhook progress bucket was dispatched.

last_webhook_dispatched_at
string | null

ISO timestamp for the most recent webhook dispatch attempt.

usage
object
error
unknown
Last modified on September 6, 2026