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

# Crear vídeo

> Crea un trabajo de generación de vídeo asíncrona. Consulte la `polling_url` devuelta cada 20 segundos hasta que el trabajo alcance un estado final.

Requiere acceso a la versión preliminar del espacio de trabajo. Consulta [Trabajos de vídeo y procesamiento por lotes](../../guides/async-video-and-batch.mdx) para la configuración, los webhooks y la gestión de resultados.


## OpenAPI

````yaml es/openapi/v1/openapi.localized.yaml POST /videos
openapi: 3.0.3
info:
  title: Phaseo Gateway API
  description: >-
    Una API de pasarela para acceder a diversos modelos de IA mediante endpoints
    compatibles con OpenAI.
  version: 1.0.0
  contact:
    name: Phaseo
    url: https://phaseo.app
    email: danielbutler500@gmail.com
servers:
  - url: https://api.phaseo.app/v1
    description: Enrutamiento global
security:
  - BearerAuth: []
tags:
  - name: Gateway
    description: Core Phaseo Gateway operations.
paths:
  /videos:
    post:
      tags:
        - Gateway
      summary: Crear vídeo
      description: >-
        Crea un trabajo de generación de vídeo asíncrona. Consulte la
        `polling_url` devuelta cada 20 segundos hasta que el trabajo alcance un
        estado final.
      operationId: createVideo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoGenerationRequest'
      responses:
        '202':
          description: Respuesta de vídeo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoGenerationResponse'
components:
  schemas:
    VideoGenerationRequest:
      type: object
      required:
        - model
        - prompt
      properties:
        model:
          type: string
        prompt:
          type: string
        duration:
          type: integer
          description: Duración deseada en segundos (depende del proveedor/modelo).
        input_video_duration:
          type: number
          format: double
          minimum: 0
          maximum: 3600
          exclusiveMinimum: true
          description: >-
            Duración del vídeo de origen en segundos. Obligatoria cuando el
            proveedor factura la duración del vídeo de origen por separado de la
            salida generada.
        input_audio_duration:
          type: number
          format: double
          minimum: 2
          maximum: 20
          description: >-
            Duración declarada del audio de origen en segundos, usada para
            validar el intervalo admitido por el proveedor. Los proveedores que
            no informan del uso definitivo pueden facturar según el máximo de
            duración de entrada que admiten.
        size:
          type: string
          description: >-
            Dimensiones explícitas (por ejemplo, 1280x720). No puede combinarse
            con resolution ni aspect_ratio.
        resolution:
          type: string
          description: >-
            480p, 720p, 1080p, 1K, 2K, 4K. Puede combinarse con aspect_ratio. No
            puede combinarse con size.
        aspect_ratio:
          type: string
          description: >-
            Relación de aspecto como 16:9, 9:16 o 1:1. Puede combinarse con
            resolution. No puede combinarse con 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: >-
            Entradas HTTPS de imagen, audio o vídeo que condicionan la
            generación. Los tipos, roles, cantidades y combinaciones admitidos
            dependen del modelo seleccionado. Consulte GET /videos/models antes
            de enviar un trabajo. El alias de compatibilidad singular
            input_reference, omitido en este esquema, acepta una imagen
            multipart o un objeto con exactamente uno de file_id o image_url. La
            compatibilidad depende del proveedor.
          items:
            $ref: '#/components/schemas/VideoInputReference'
        frame_images:
          type: array
          minItems: 1
          maxItems: 2
          description: >-
            Imágenes HTTPS del primer/último fotograma. Cada frame_type puede
            aparecer una vez. No proporcione además input_reference ni roles de
            fotograma en 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: >-
            Solo extensiones específicas del proveedor. Se rechazan el paso
            completo de la solicitud y los campos duplicados de enrutamiento,
            prompt, callback o facturación.
        provider_options:
          type: object
          additionalProperties:
            type: object
            additionalProperties: true
          description: >-
            Extensiones identificadas por el ID canónico del proveedor (por
            ejemplo, atlascloud o byteplus). Solo se reenvían las opciones del
            proveedor seleccionado. No puede combinarse con provider_params. Los
            campos de enrutamiento, prompt, callback, duración, resolución y
            cantidad de salidas deben usar campos validados de nivel superior.
        output:
          $ref: '#/components/schemas/VideoOutputConfig'
        webhook:
          type: object
          required:
            - endpoint_id
          additionalProperties: false
          properties:
            endpoint_id:
              type: string
              description: >-
                Endpoint de webhook activo gestionado por el espacio de trabajo.
                Su secreto de firma cifrado y rotativo nunca se almacena en los
                metadatos del trabajo de vídeo.
            events:
              type: array
              description: >-
                Suscripciones opcionales a eventos. Use eventos genéricos job.*
                o eventos video.* correspondientes, por ejemplo
                video.status_changed, video.progress o video.completed. Si se
                omiten, se usan job.status_changed y eventos finales job.*.
                Incluya job.progress o video.progress explícitamente para
                callbacks de progreso. Si se especifican, al menos un evento
                debe ser válido para trabajos de vídeo; se rechazan las listas
                mal formadas o compuestas solo de eventos de otro tipo.
              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: >-
            URL de WebSocket para suscribirse a actualizaciones normalizadas del
            ciclo de vida de trabajos asíncronos.
        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: >-
            Estado normalizado del ciclo de vida asíncrono para consumidores de
            sondeo, WebSocket y webhooks.
        cancel_url:
          type: string
          format: uri
          nullable: true
          description: Reservado por compatibilidad; actualmente siempre es null.
        output_access:
          type: string
          enum:
            - bytes
            - signed_url
            - both
        generation_id:
          type: string
          nullable: true
        native_video_id:
          type: string
          nullable: true
          description: >-
            ID de vídeo/trabajo nativo del proveedor cuando difiere del ID
            propio de la pasarela.
        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: Presente cuando output_access incluye bytes (endpoint autenticado).
        download_url:
          type: string
          nullable: true
          description: >-
            URL firmada de primera parte para descarga directa cuando el estado
            es completed.
        expires_at:
          type: integer
          nullable: true
          description: >-
            Marca de tiempo Unix (segundos) de caducidad de la download_url
            firmada.
        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: >-
            Marca de tiempo ISO del próximo reintento programado del webhook del
            usuario, si está en cola.
        last_webhook_progress:
          type: number
          nullable: true
          description: >-
            Último intervalo aproximado de progreso enviado a los consumidores
            de webhooks.
        last_webhook_progress_at:
          type: string
          nullable: true
          description: >-
            Marca de tiempo ISO del envío del intervalo de progreso más reciente
            del webhook.
        last_webhook_dispatched_at:
          type: string
          nullable: true
          description: Marca de tiempo ISO del intento de envío del webhook más reciente.
        usage:
          type: object
          properties:
            cost:
              type: number
            is_byok:
              type: boolean
          additionalProperties: true
        error:
          nullable: true
    VideoInputReference:
      description: >-
        Entrada multimedia HTTPS tipada. Use image_url para imágenes y media_url
        para audio o vídeo. Los roles describen cómo debe usar el modelo la
        entrada; la compatibilidad varía según el proveedor y el modelo.
      oneOf:
        - type: object
          required:
            - type
            - image_url
          properties:
            type:
              type: string
              enum:
                - image_url
            role:
              type: string
              description: Uso previsto de esta imagen por el modelo seleccionado.
              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: URL HTTPS de imagen accesible públicamente.
        - type: object
          required:
            - type
            - media_url
          properties:
            type:
              type: string
              enum:
                - video_url
                - audio_url
            role:
              type: string
              description: Uso previsto de este audio o vídeo por el modelo seleccionado.
              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: URL HTTPS de audio o vídeo accesible públicamente.
    VideoOutputConfig:
      type: object
      properties:
        access:
          type: string
          enum:
            - bytes
            - signed_url
            - both
          default: both
          description: >-
            bytes=solo content_url autenticada, signed_url=solo enlaces de
            descarga firmados, both=incluir ambos.
    ProviderRoutingOptions:
      type: object
      description: >-
        Preferencias de enrutamiento de proveedores para la selección de la
        pasarela.
      properties:
        order:
          type: array
          items:
            type: string
        only:
          type: array
          items:
            type: string
        ignore:
          type: array
          items:
            type: string
        include_alpha:
          type: boolean
          description: >-
            Incluir proveedores alpha en el enrutamiento (desactivado de forma
            predeterminada).
        allow_fallbacks:
          type: boolean
          nullable: true
          description: Permitir recurrir a otro proveedor apto tras un fallo.
        require_parameters:
          type: boolean
          nullable: true
          description: >-
            Exigir que el proveedor admita los parámetros solicitados antes del
            enrutamiento.
        required_execution_region:
          type: string
          nullable: true
          description: >-
            Restringir el enrutamiento a proveedores con la región de ejecución
            solicitada.
        required_data_region:
          type: string
          nullable: true
          description: >-
            Restringir el enrutamiento a proveedores con la región de datos
            solicitada.
        require_zero_data_retention:
          type: boolean
          nullable: true
          description: >-
            Restringir el enrutamiento a proveedores que admiten la retención
            cero de datos.
        data_collection:
          type: string
          nullable: true
          enum:
            - allow
            - deny
        zdr:
          type: boolean
          nullable: true
        enforce_distillable_text:
          type: boolean
          nullable: true
        quantizations:
          type: array
          nullable: true
          items:
            type: string
        sort:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
          description: >-
            Ordenar los proveedores para esta solicitud, por ejemplo, por
            precio, latencia o rendimiento.
        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: Presente cuando output_access incluye bytes.
        download_url:
          type: string
          description: URL firmada de primera parte para esta salida.
        expires_at:
          type: integer
          description: Marca de tiempo Unix (segundos) de caducidad de esta URL de salida.
    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: >-
        Configuración depurada del webhook asíncrono y estado de entrega. Nunca
        se devuelven secretos; `has_secret` indica si las entregas firmadas
        están habilitadas. Las entregas firmadas incluyen las cabeceras
        x-phaseo-signature, x-phaseo-timestamp, x-phaseo-event-id,
        x-phaseo-event-type, x-phaseo-delivery-key, x-phaseo-attempt y
        x-phaseo-max-attempts.
      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: >-
        Resumen público de entrega de webhooks asíncronos gestionados por la
        pasarela. Permite distinguir el estado de ejecución del trabajo del
        estado de entrega del webhook.
      properties:
        total_attempts:
          type: integer
          description: Total de intentos de entrega registrados para este trabajo.
        delivered_events:
          type: integer
          description: Número de claves de entrega que han alcanzado el estado entregado.
        delivered_event_types:
          type: array
          description: Claves de entrega entregadas al menos una vez.
          items:
            type: string
          example:
            - video.completed
        pending_retries:
          type: integer
          description: Número de claves de entrega con un reintento programado actualmente.
        next_retry_at:
          type: string
          nullable: true
          description: Marca de tiempo ISO del próximo reintento programado, si existe.
        last_attempt_at:
          type: string
          nullable: true
          description: Marca de tiempo ISO del intento de entrega más reciente.
        last_attempt_status:
          type: string
          nullable: true
          enum:
            - delivered
            - scheduled_retry
            - failed_permanently
          description: Resultado del intento de entrega más reciente.
        last_response_status:
          type: integer
          nullable: true
          description: Estado HTTP devuelto por el destino del webhook, si está disponible.
        last_delivered_at:
          type: string
          nullable: true
          description: Marca de tiempo ISO de la entrega correcta más reciente.
        last_failure_at:
          type: string
          nullable: true
          description: Marca de tiempo ISO del intento fallido o en reintento más reciente.
        last_error_message:
          type: string
          nullable: true
          description: Mensaje de error de entrega más reciente, si está disponible.
    AsyncWebhookDeliveryAttempt:
      type: object
      description: >-
        Intento reciente de entrega de un webhook asíncrono gestionado por la
        pasarela.
      properties:
        id:
          type: string
          description: Identificador estable del intento para auditoría y depuración.
        delivery_key:
          type: string
          description: Clave de idempotencia para la entrega de este evento.
          example: video.completed
        event_type:
          type: string
          description: Tipo de evento entregado al destino del webhook.
          example: video.completed
        status:
          type: string
          enum:
            - delivered
            - scheduled_retry
            - failed_permanently
        attempt_number:
          type: integer
          description: Número de intento para esta clave de entrega, comenzando en uno.
        max_attempts:
          type: integer
          description: >-
            Máximo de intentos antes de marcar la entrega como fallida
            permanentemente.
        tried_at:
          type: string
          description: Marca de tiempo ISO de este intento.
        delivered_at:
          type: string
          nullable: true
          description: Marca de tiempo ISO de la entrega correcta de este intento.
        next_retry_at:
          type: string
          nullable: true
          description: >-
            Marca de tiempo ISO del próximo reintento tras este intento, si está
            programado.
        response_status:
          type: integer
          nullable: true
          description: Estado HTTP devuelto por el destino del webhook, si está disponible.
        error_message:
          type: string
          nullable: true
          description: Mensaje de error de entrega, si está disponible.
        response_body_preview:
          type: string
          nullable: true
          description: >-
            Vista previa del cuerpo de respuesta del destino del webhook con
            información sensible oculta.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Autenticación con token Bearer

````

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