Gateway

Create video

Creates an async video generation job. Poll the returned polling_url every 20 seconds until the job reaches a terminal status.

post/videos

Request

  • Base URL: https://api.phaseo.app/v1
  • URL: https://api.phaseo.app/v1/videos
  • Auth: HTTP bearer

Request body

modelstring required
modelsstring[]

Optional ordered fallback models tried after model. model is required and is always the primary model. When an attempt fails with 429, 500, 502, 503, or 504, the next entry is tried; other errors are returned unchanged. Accepts up to 25 model IDs or presets; duplicates and entries equal to model are ignored. Each attempt is validated, logged, and billed as its own request, and the response model field and routing trace show the model that served the request. Streaming requests fall back only before the first byte, and video and music jobs fall back only at submission. Batch, realtime, and council requests reject models. Fallbacks set on a dynamic route take precedence, and phaseo/auto cannot be combined with models.

promptstring required
durationinteger

Desired duration in seconds (provider/model dependent).

input_video_durationnumber double

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

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

sizestring

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

resolutionstring

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

aspect_ratiostring

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

seedinteger
sample_countinteger
negative_promptstring
generate_audioboolean
enhance_promptboolean
compression_qualityinteger
person_generationstring
resize_modestring
provider_paramsobject

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

provider_optionsobject

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.

Example request

{
  "models": [
    "anthropic/claude-sonnet-5-5",
    "google/gemini-2.5-flash"
  ]
}

Response

Video response

idstring
polling_urlstring
websocket_urlstring uri

WebSocket URL for subscribing to normalized async job lifecycle updates.

modelstring
request_idstring
session_idstring
status'queued' | 'processing' | 'completed' | 'failed' | 'cancelled' | 'expired'
lifecycle_status'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'expired'

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

cancel_urlstring uri nullable

Reserved for compatibility; currently always null.

output_access'bytes' | 'signed_url' | 'both'
generation_idstring nullable
native_video_idstring nullable

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

objectstring
poll_after_secondsinteger
providerstring
secondsnumber
sizestring
audioboolean
content_urlstring

Present when output_access includes bytes (authenticated endpoint).

download_urlstring nullable

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

expires_atinteger nullable

Unix timestamp (seconds) when the signed download_url expires.

progressinteger nullable
progress_sourcestring
next_webhook_retry_atstring nullable

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

last_webhook_progressnumber nullable

Most recent coarse progress bucket dispatched to webhook consumers.

last_webhook_progress_atstring nullable

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

last_webhook_dispatched_atstring nullable

ISO timestamp for the most recent webhook dispatch attempt.

errorunknown

Example response

{
  "object": "video",
  "poll_after_seconds": 20,
  "webhook": {
    "delivery": {
      "delivered_event_types": [
        "video.completed"
      ]
    },
    "attempts": [
      {
        "delivery_key": "video.completed",
        "event_type": "video.completed"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.