> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# Create video

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

Requires workspace preview access. See [Video and batch jobs](https://phaseo.app/docs/v1/guides/async-video-and-batch.md) for setup, webhooks, and result handling.


## OpenAPI

````yaml openapi/v1/openapi.yaml POST /videos
openapi: 3.0.3
info:
  title: Phaseo Gateway API
  description: >-
    A gateway API for accessing various AI models with OpenAI-compatible
    endpoints.
  version: 1.0.0
  contact:
    name: Phaseo
    url: https://phaseo.app
    email: danielbutler500@gmail.com
servers:
  - url: https://api.phaseo.app/v1
    description: Global routing
security:
  - BearerAuth: []
tags:
  - name: Gateway
    description: Core Phaseo Gateway operations.
paths:
  /videos:
    post:
      tags:
        - Gateway
      summary: Create video
      description: >-
        Creates an async video generation job. Poll the returned `polling_url`
        every 20 seconds until the job reaches a terminal status.
      operationId: createVideo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoGenerationRequest'
      responses:
        '202':
          description: Video response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoGenerationResponse'
components:
  schemas:
    VideoGenerationRequest:
      type: object
      required:
        - model
        - prompt
      properties:
        model:
          type: string
        models:
          $ref: '#/components/schemas/ModelFallbacks'
        prompt:
          type: string
        duration:
          type: integer
          description: Desired duration in seconds (provider/model dependent).
        input_video_duration:
          type: number
          format: double
          minimum: 0
          maximum: 3600
          exclusiveMinimum: true
          description: >-
            Duration of the source video in seconds. Required when a provider
            bills source-video duration independently from generated output.
        input_audio_duration:
          type: number
          format: double
          minimum: 2
          maximum: 20
          description: >-
            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.
        size:
          type: string
          description: >-
            Explicit dimensions (for example 1280x720). Cannot be combined with
            resolution or aspect_ratio.
        resolution:
          type: string
          description: >-
            480p, 720p, 1080p, 1K, 2K, 4K. Can be combined with aspect_ratio.
            Cannot be combined with size.
        aspect_ratio:
          type: string
          description: >-
            Aspect ratio such as 16:9, 9:16, 1:1. Can be combined with
            resolution. Cannot be combined with size.
        seed:
          type: integer
        sample_count:
          type: integer
          minimum: 1
          maximum: 4
        negative_prompt:
          type: string
        generate_audio:
          type: boolean
        enhance_prompt:
          type: boolean
        compression_quality:
          type: integer
        person_generation:
          type: string
        resize_mode:
          type: string
        input_references:
          type: array
          description: >-
            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.
          items:
            $ref: '#/components/schemas/VideoInputReference'
        frame_images:
          type: array
          minItems: 1
          maxItems: 2
          description: >-
            HTTPS first/last frame images. Each frame_type may appear once. Do
            not also supply input_reference or frame roles in input_references.
          items:
            type: object
            additionalProperties: false
            required:
              - type
              - frame_type
              - image_url
            properties:
              type:
                type: string
                enum:
                  - image_url
              frame_type:
                type: string
                enum:
                  - first_frame
                  - last_frame
              image_url:
                type: object
                required:
                  - url
                properties:
                  url:
                    type: string
                    format: uri
        provider_params:
          type: object
          additionalProperties: true
          description: >-
            Provider-specific extensions only. Complete request passthrough and
            duplicate routing, prompt, callback, or billing fields are rejected.
        provider_options:
          type: object
          additionalProperties:
            type: object
            additionalProperties: true
          description: >-
            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:
          $ref: '#/components/schemas/VideoOutputConfig'
        webhook:
          type: object
          required:
            - endpoint_id
          additionalProperties: false
          properties:
            endpoint_id:
              type: string
              description: >-
                Active workspace-managed webhook endpoint. Its encrypted,
                rotatable signing secret is never stored in video job metadata.
            events:
              type: array
              description: >-
                Optional event subscriptions. Use generic job.* events or
                matching video.* events, for example video.status_changed,
                video.progress, or video.completed. When omitted,
                job.status_changed and terminal job.* events are used. Include
                job.progress or video.progress explicitly for progress
                callbacks. When supplied, at least one event must be valid for
                video jobs; cross-kind-only or malformed event lists are
                rejected.
              items:
                type: string
        provider:
          $ref: '#/components/schemas/ProviderRoutingOptions'
    VideoGenerationResponse:
      type: object
      properties:
        id:
          type: string
        polling_url:
          type: string
        websocket_url:
          type: string
          format: uri
          description: >-
            WebSocket URL for subscribing to normalized async job lifecycle
            updates.
        model:
          type: string
        request_id:
          type: string
        session_id:
          type: string
        status:
          type: string
          enum:
            - queued
            - processing
            - completed
            - failed
            - cancelled
            - expired
        lifecycle_status:
          type: string
          enum:
            - pending
            - running
            - completed
            - failed
            - cancelled
            - expired
          description: >-
            Normalized async lifecycle status for polling, websocket, and
            webhook consumers.
        cancel_url:
          type: string
          format: uri
          nullable: true
          description: Reserved for compatibility; currently always null.
        output_access:
          type: string
          enum:
            - bytes
            - signed_url
            - both
        generation_id:
          type: string
          nullable: true
        native_video_id:
          type: string
          nullable: true
          description: >-
            Provider-native video/job id when it differs from the gateway-owned
            id.
        created_at:
          oneOf:
            - type: integer
            - type: string
        started_at:
          nullable: true
          oneOf:
            - type: integer
            - type: string
        completed_at:
          nullable: true
          oneOf:
            - type: integer
            - type: string
        object:
          type: string
          example: video
        poll_after_seconds:
          type: integer
          example: 20
        provider:
          type: string
        seconds:
          type: number
        size:
          type: string
        audio:
          type: boolean
        content_url:
          type: string
          description: Present when output_access includes bytes (authenticated endpoint).
        download_url:
          type: string
          nullable: true
          description: Signed first-party URL for direct download when status is completed.
        expires_at:
          type: integer
          nullable: true
          description: Unix timestamp (seconds) when the signed download_url expires.
        progress:
          type: integer
          nullable: true
        progress_source:
          type: string
        asset:
          type: object
          nullable: true
          properties:
            id:
              type: string
            mime_type:
              type: string
            bytes:
              type: integer
            sha256:
              type: string
            width:
              type: integer
            height:
              type: integer
            duration_seconds:
              type: number
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/VideoOutput'
        billing:
          $ref: '#/components/schemas/VideoBillingSummary'
        webhook:
          $ref: '#/components/schemas/AsyncWebhookPublicState'
        next_webhook_retry_at:
          type: string
          nullable: true
          description: >-
            ISO timestamp for the next scheduled user-webhook retry, when
            queued.
        last_webhook_progress:
          type: number
          nullable: true
          description: Most recent coarse progress bucket dispatched to webhook consumers.
        last_webhook_progress_at:
          type: string
          nullable: true
          description: >-
            ISO timestamp when the most recent webhook progress bucket was
            dispatched.
        last_webhook_dispatched_at:
          type: string
          nullable: true
          description: ISO timestamp for the most recent webhook dispatch attempt.
        usage:
          type: object
          properties:
            cost:
              type: number
            is_byok:
              type: boolean
          additionalProperties: true
        error:
          nullable: true
    ModelFallbacks:
      type: array
      minItems: 1
      maxItems: 25
      items:
        type: string
        minLength: 1
      description: >-
        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`.
      example:
        - anthropic/claude-sonnet-5-5
        - google/gemini-2.5-flash
    VideoInputReference:
      description: >-
        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.
      oneOf:
        - type: object
          required:
            - type
            - image_url
          properties:
            type:
              type: string
              enum:
                - image_url
            role:
              type: string
              description: Intended use of this image by the selected model.
              enum:
                - first_frame
                - last_frame
                - reference
                - source
                - mask
            reference_type:
              type: string
            image_url:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  format: uri
                  description: Publicly reachable HTTPS image URL.
        - type: object
          required:
            - type
            - media_url
          properties:
            type:
              type: string
              enum:
                - video_url
                - audio_url
            role:
              type: string
              description: Intended use of this audio or video by the selected model.
              enum:
                - first_frame
                - last_frame
                - reference
                - source
                - mask
            reference_type:
              type: string
            media_url:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  format: uri
                  description: Publicly reachable HTTPS audio or video URL.
    VideoOutputConfig:
      type: object
      properties:
        access:
          type: string
          enum:
            - bytes
            - signed_url
            - both
          default: both
          description: >-
            bytes=authenticated content_url only, signed_url=signed download
            links only, both=include both.
    ProviderRoutingOptions:
      type: object
      description: Provider routing preferences for gateway selection.
      properties:
        order:
          type: array
          items:
            type: string
        only:
          type: array
          items:
            type: string
        ignore:
          type: array
          items:
            type: string
        include_alpha:
          type: boolean
          description: Include alpha providers in routing (off by default).
        allow_fallbacks:
          type: boolean
          nullable: true
          description: Allow fallback to another eligible provider after failure.
        require_parameters:
          type: boolean
          nullable: true
          description: Require provider support for requested parameters before routing.
        required_execution_region:
          type: string
          nullable: true
          description: Restrict routing to providers with the requested execution region.
        required_data_region:
          type: string
          nullable: true
          description: Restrict routing to providers with the requested data region.
        require_zero_data_retention:
          type: boolean
          nullable: true
          description: Restrict routing to providers that support zero data retention.
        data_collection:
          type: string
          nullable: true
          description: >-
            `allow` (the default) filters nothing. `deny` is not supported yet
            and returns 400 unsupported_routing_filter.
          enum:
            - allow
            - deny
        zdr:
          type: boolean
          nullable: true
        enforce_distillable_text:
          type: boolean
          nullable: true
          description: >-
            `false` (the default) filters nothing. `true` is not supported yet
            and returns 400 unsupported_routing_filter.
        quantizations:
          type: array
          nullable: true
          items:
            type: string
        sort:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
          description: >-
            Rank providers for this request, for example by price, latency, or
            throughput.
        max_price:
          type: object
          properties:
            prompt:
              oneOf:
                - type: number
                - type: string
            completion:
              oneOf:
                - type: number
                - type: string
            image:
              oneOf:
                - type: number
                - type: string
            audio:
              oneOf:
                - type: number
                - type: string
            request:
              oneOf:
                - type: number
                - type: string
        preferred_min_throughput:
          oneOf:
            - type: number
            - type: object
              additionalProperties:
                type: number
        preferred_max_latency:
          oneOf:
            - type: number
            - type: object
              additionalProperties:
                type: number
    VideoOutput:
      type: object
      properties:
        index:
          type: integer
        mime_type:
          type: string
        bytes_available:
          type: boolean
        content_url:
          type: string
          description: Present when output_access includes bytes.
        download_url:
          type: string
          description: Signed first-party URL for this output.
        expires_at:
          type: integer
          description: Unix timestamp (seconds) when this output URL expires.
    VideoBillingSummary:
      type: object
      properties:
        currency:
          type: string
        estimated_provider_cost:
          type: string
          nullable: true
        estimated_user_cost:
          type: string
          nullable: true
        settled_provider_cost:
          type: string
          nullable: true
        settled_user_cost:
          type: string
          nullable: true
        state:
          type: string
          enum:
            - pending
            - estimated
            - settled
            - void
        billable:
          type: boolean
        total_nanos:
          type: integer
          nullable: true
        estimated_nanos:
          type: integer
          nullable: true
        reserved_nanos:
          type: integer
          nullable: true
        reservation_id:
          type: string
          nullable: true
        reservation_status:
          type: string
          nullable: true
        charge_reason:
          type: string
          nullable: true
        charged:
          type: boolean
          nullable: true
        billed_at:
          type: string
      additionalProperties: true
    AsyncWebhookPublicState:
      type: object
      description: >-
        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.
      properties:
        url:
          type: string
          format: uri
          nullable: true
        events:
          type: array
          items:
            type: string
        has_secret:
          type: boolean
        delivery:
          $ref: '#/components/schemas/AsyncWebhookDeliverySummary'
        attempts:
          type: array
          items:
            $ref: '#/components/schemas/AsyncWebhookDeliveryAttempt'
    AsyncWebhookDeliverySummary:
      type: object
      description: >-
        Public delivery summary for gateway-managed async webhooks. Use this to
        distinguish job execution state from webhook delivery health.
      properties:
        total_attempts:
          type: integer
          description: Total delivery attempts recorded for this job.
        delivered_events:
          type: integer
          description: Number of delivery keys that have reached a delivered state.
        delivered_event_types:
          type: array
          description: Delivery keys that have been delivered at least once.
          items:
            type: string
          example:
            - video.completed
        pending_retries:
          type: integer
          description: Number of delivery keys currently scheduled for retry.
        next_retry_at:
          type: string
          nullable: true
          description: ISO timestamp for the next scheduled retry, when present.
        last_attempt_at:
          type: string
          nullable: true
          description: ISO timestamp for the most recent delivery attempt.
        last_attempt_status:
          type: string
          nullable: true
          enum:
            - delivered
            - scheduled_retry
            - failed_permanently
          description: Result of the most recent delivery attempt.
        last_response_status:
          type: integer
          nullable: true
          description: HTTP status returned by the webhook destination, when available.
        last_delivered_at:
          type: string
          nullable: true
          description: ISO timestamp for the most recent successful delivery.
        last_failure_at:
          type: string
          nullable: true
          description: ISO timestamp for the most recent failed or retrying attempt.
        last_error_message:
          type: string
          nullable: true
          description: Most recent delivery error message, when available.
    AsyncWebhookDeliveryAttempt:
      type: object
      description: Recent gateway-managed async webhook delivery attempt.
      properties:
        id:
          type: string
          description: Stable attempt identifier for audit and debugging.
        delivery_key:
          type: string
          description: Idempotency key for this event delivery.
          example: video.completed
        event_type:
          type: string
          description: Event type delivered to the webhook destination.
          example: video.completed
        status:
          type: string
          enum:
            - delivered
            - scheduled_retry
            - failed_permanently
        attempt_number:
          type: integer
          description: One-based attempt number for this delivery key.
        max_attempts:
          type: integer
          description: Maximum attempts before the delivery is marked failed permanently.
        tried_at:
          type: string
          description: ISO timestamp when this attempt was made.
        delivered_at:
          type: string
          nullable: true
          description: ISO timestamp when this attempt was delivered successfully.
        next_retry_at:
          type: string
          nullable: true
          description: ISO timestamp for the next retry after this attempt, when scheduled.
        response_status:
          type: integer
          nullable: true
          description: HTTP status returned by the webhook destination, when available.
        error_message:
          type: string
          nullable: true
          description: Delivery error message, when available.
        response_body_preview:
          type: string
          nullable: true
          description: Redacted response body preview from the webhook destination.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.