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

# Créer une vidéo

> Crée une tâche de génération vidéo asynchrone. Interrogez la `polling_url` renvoyée toutes les 20 secondes jusqu’à ce que la tâche atteigne un état final.

Nécessite l’accès à la préversion dans l’espace de travail. Consultez [Tâches vidéo et traitement par lots](../../guides/async-video-and-batch.mdx) pour la configuration, les webhooks et le traitement des résultats.


## OpenAPI

````yaml fr/openapi/v1/openapi.localized.yaml POST /videos
openapi: 3.0.3
info:
  title: Phaseo Gateway API
  description: >-
    Une API de passerelle pour accéder à divers modèles d’IA via des points de
    terminaison compatibles avec OpenAI.
  version: 1.0.0
  contact:
    name: Phaseo
    url: https://phaseo.app
    email: danielbutler500@gmail.com
servers:
  - url: https://api.phaseo.app/v1
    description: Routage mondial
security:
  - BearerAuth: []
tags:
  - name: Gateway
    description: Core Phaseo Gateway operations.
paths:
  /videos:
    post:
      tags:
        - Gateway
      summary: Créer une vidéo
      description: >-
        Crée une tâche de génération vidéo asynchrone. Interrogez la
        `polling_url` renvoyée toutes les 20 secondes jusqu’à ce que la tâche
        atteigne un état final.
      operationId: createVideo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoGenerationRequest'
      responses:
        '202':
          description: Réponse vidéo
          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: Durée souhaitée en secondes (selon le fournisseur/modèle).
        input_video_duration:
          type: number
          format: double
          minimum: 0
          maximum: 3600
          exclusiveMinimum: true
          description: >-
            Durée de la vidéo source en secondes. Obligatoire si le fournisseur
            facture cette durée séparément de la sortie générée.
        input_audio_duration:
          type: number
          format: double
          minimum: 2
          maximum: 20
          description: >-
            Durée déclarée de l’audio source en secondes, utilisée pour valider
            la plage du fournisseur. Les fournisseurs qui ne communiquent pas
            une consommation faisant autorité peuvent facturer selon leur durée
            d’entrée maximale prise en charge.
        size:
          type: string
          description: >-
            Dimensions explicites (par exemple 1280x720). Incompatible avec
            resolution ou aspect_ratio.
        resolution:
          type: string
          description: >-
            480p, 720p, 1080p, 1K, 2K, 4K. Compatible avec aspect_ratio.
            Incompatible avec size.
        aspect_ratio:
          type: string
          description: >-
            Format d’image tel que 16:9, 9:16 ou 1:1. Compatible avec
            resolution. Incompatible avec 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: >-
            Entrées HTTPS d’image, d’audio ou de vidéo conditionnant la
            génération. Les types, rôles, nombres et combinaisons pris en charge
            dépendent du modèle choisi. Consultez GET /videos/models avant
            d’envoyer une tâche. L’alias de compatibilité au singulier
            input_reference, absent de ce schéma, accepte une image multipart ou
            un objet contenant exactement un champ parmi file_id et image_url.
            La prise en charge dépend du fournisseur.
          items:
            $ref: '#/components/schemas/VideoInputReference'
        frame_images:
          type: array
          minItems: 1
          maxItems: 2
          description: >-
            Images HTTPS de la première/dernière image. Chaque frame_type ne
            peut apparaître qu’une fois. Ne fournissez pas également
            input_reference ou de rôles d’image dans 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: >-
            Extensions propres au fournisseur uniquement. La transmission
            intégrale de la requête et les doublons de champs de routage,
            prompt, callback ou facturation sont rejetés.
        provider_options:
          type: object
          additionalProperties:
            type: object
            additionalProperties: true
          description: >-
            Extensions indexées par ID canonique du fournisseur (par exemple
            atlascloud ou byteplus). Seules les options du fournisseur choisi
            sont transmises. Incompatible avec provider_params. Le routage,
            prompt, callback, la durée, résolution et le nombre de sorties
            doivent utiliser les champs de premier niveau validés.
        output:
          $ref: '#/components/schemas/VideoOutputConfig'
        webhook:
          type: object
          required:
            - endpoint_id
          additionalProperties: false
          properties:
            endpoint_id:
              type: string
              description: >-
                Endpoint webhook actif géré par l’espace de travail. Son secret
                de signature chiffré et renouvelable n’est jamais stocké dans
                les métadonnées de la tâche vidéo.
            events:
              type: array
              description: >-
                Abonnements facultatifs aux événements. Utilisez les événements
                génériques job.* ou les événements video.* correspondants, par
                exemple video.status_changed, video.progress ou video.completed.
                Par défaut, job.status_changed et les événements finaux job.*
                sont utilisés. Incluez explicitement job.progress ou
                video.progress pour les callbacks de progression. Si la liste
                est fournie, au moins un événement doit être valide pour les
                tâches vidéo ; les listes mal formées ou ne contenant que des
                événements d’un autre type sont rejetées.
              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 WebSocket permettant de s’abonner aux mises à jour normalisées
            du cycle de vie des tâches asynchrones.
        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: >-
            État normalisé du cycle de vie asynchrone pour les consommateurs par
            interrogation, WebSocket et webhook.
        cancel_url:
          type: string
          format: uri
          nullable: true
          description: Réservé à la compatibilité ; actuellement toujours 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 vidéo/tâche natif du fournisseur lorsqu’il diffère de l’ID de la
            passerelle.
        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: Présent lorsque output_access inclut bytes (endpoint authentifié).
        download_url:
          type: string
          nullable: true
          description: >-
            URL signée de première partie pour le téléchargement direct lorsque
            l’état est completed.
        expires_at:
          type: integer
          nullable: true
          description: Horodatage Unix (secondes) d’expiration de la download_url signée.
        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: >-
            Horodatage ISO de la prochaine tentative programmée du webhook
            utilisateur, si en attente.
        last_webhook_progress:
          type: number
          nullable: true
          description: >-
            Dernière tranche de progression approximative envoyée aux
            consommateurs de webhooks.
        last_webhook_progress_at:
          type: string
          nullable: true
          description: >-
            Horodatage ISO de l’envoi de la dernière tranche de progression du
            webhook.
        last_webhook_dispatched_at:
          type: string
          nullable: true
          description: Horodatage ISO de la tentative d’envoi du webhook la plus récente.
        usage:
          type: object
          properties:
            cost:
              type: number
            is_byok:
              type: boolean
          additionalProperties: true
        error:
          nullable: true
    VideoInputReference:
      description: >-
        Entrée multimédia HTTPS typée. Utilisez image_url pour les images et
        media_url pour l’audio ou la vidéo. Les rôles décrivent l’utilisation de
        l’entrée par le modèle ; la prise en charge varie selon le fournisseur
        et le modèle.
      oneOf:
        - type: object
          required:
            - type
            - image_url
          properties:
            type:
              type: string
              enum:
                - image_url
            role:
              type: string
              description: Utilisation prévue de cette image par le modèle choisi.
              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 d’image accessible publiquement.
        - type: object
          required:
            - type
            - media_url
          properties:
            type:
              type: string
              enum:
                - video_url
                - audio_url
            role:
              type: string
              description: >-
                Utilisation prévue de cet audio ou de cette vidéo par le modèle
                choisi.
              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 d’audio ou de vidéo accessible publiquement.
    VideoOutputConfig:
      type: object
      properties:
        access:
          type: string
          enum:
            - bytes
            - signed_url
            - both
          default: both
          description: >-
            bytes=content_url authentifiée uniquement, signed_url=liens de
            téléchargement signés uniquement, both=inclure les deux.
    ProviderRoutingOptions:
      type: object
      description: >-
        Préférences de routage des fournisseurs pour la sélection par la
        passerelle.
      properties:
        order:
          type: array
          items:
            type: string
        only:
          type: array
          items:
            type: string
        ignore:
          type: array
          items:
            type: string
        include_alpha:
          type: boolean
          description: >-
            Inclure les fournisseurs alpha dans le routage (désactivé par
            défaut).
        allow_fallbacks:
          type: boolean
          nullable: true
          description: >-
            Autoriser le repli vers un autre fournisseur éligible après un
            échec.
        require_parameters:
          type: boolean
          nullable: true
          description: >-
            Exiger la prise en charge des paramètres demandés par le fournisseur
            avant le routage.
        required_execution_region:
          type: string
          nullable: true
          description: >-
            Limiter le routage aux fournisseurs disposant de la région
            d’exécution demandée.
        required_data_region:
          type: string
          nullable: true
          description: >-
            Limiter le routage aux fournisseurs disposant de la région de
            données demandée.
        require_zero_data_retention:
          type: boolean
          nullable: true
          description: >-
            Limiter le routage aux fournisseurs qui prennent en charge la
            conservation nulle des données.
        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: >-
            Classer les fournisseurs pour cette requête, par exemple selon le
            prix, la latence ou le débit.
        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: Présent lorsque output_access inclut bytes.
        download_url:
          type: string
          description: URL signée de première partie pour cette sortie.
        expires_at:
          type: integer
          description: Horodatage Unix (secondes) d’expiration de cette URL de sortie.
    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: >-
        Configuration nettoyée du webhook asynchrone et état de livraison. Les
        secrets ne sont jamais renvoyés ; `has_secret` indique si les livraisons
        signées sont activées. Les livraisons signées incluent les en-têtes
        x-phaseo-signature, x-phaseo-timestamp, x-phaseo-event-id,
        x-phaseo-event-type, x-phaseo-delivery-key, x-phaseo-attempt et
        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: >-
        Résumé public de livraison des webhooks asynchrones gérés par la
        passerelle. Permet de distinguer l’état d’exécution de la tâche de la
        santé de livraison du webhook.
      properties:
        total_attempts:
          type: integer
          description: >-
            Nombre total de tentatives de livraison enregistrées pour cette
            tâche.
        delivered_events:
          type: integer
          description: Nombre de clés de livraison ayant atteint l’état livré.
        delivered_event_types:
          type: array
          description: Clés de livraison livrées au moins une fois.
          items:
            type: string
          example:
            - video.completed
        pending_retries:
          type: integer
          description: >-
            Nombre de clés de livraison actuellement programmées pour une
            nouvelle tentative.
        next_retry_at:
          type: string
          nullable: true
          description: Horodatage ISO de la prochaine tentative programmée, le cas échéant.
        last_attempt_at:
          type: string
          nullable: true
          description: Horodatage ISO de la tentative de livraison la plus récente.
        last_attempt_status:
          type: string
          nullable: true
          enum:
            - delivered
            - scheduled_retry
            - failed_permanently
          description: Résultat de la tentative de livraison la plus récente.
        last_response_status:
          type: integer
          nullable: true
          description: Statut HTTP renvoyé par la destination du webhook, si disponible.
        last_delivered_at:
          type: string
          nullable: true
          description: Horodatage ISO de la livraison réussie la plus récente.
        last_failure_at:
          type: string
          nullable: true
          description: >-
            Horodatage ISO de la tentative échouée ou en cours de nouvelle
            tentative la plus récente.
        last_error_message:
          type: string
          nullable: true
          description: Message d’erreur de livraison le plus récent, si disponible.
    AsyncWebhookDeliveryAttempt:
      type: object
      description: >-
        Tentative récente de livraison d’un webhook asynchrone géré par la
        passerelle.
      properties:
        id:
          type: string
          description: Identifiant stable de tentative pour l’audit et le débogage.
        delivery_key:
          type: string
          description: Clé d’idempotence pour la livraison de cet événement.
          example: video.completed
        event_type:
          type: string
          description: Type d’événement livré à la destination du webhook.
          example: video.completed
        status:
          type: string
          enum:
            - delivered
            - scheduled_retry
            - failed_permanently
        attempt_number:
          type: integer
          description: Numéro de tentative pour cette clé de livraison, à partir de un.
        max_attempts:
          type: integer
          description: >-
            Nombre maximal de tentatives avant de marquer la livraison comme
            définitivement échouée.
        tried_at:
          type: string
          description: Horodatage ISO de cette tentative.
        delivered_at:
          type: string
          nullable: true
          description: Horodatage ISO de la livraison réussie de cette tentative.
        next_retry_at:
          type: string
          nullable: true
          description: >-
            Horodatage ISO de la prochaine tentative après celle-ci, si
            programmée.
        response_status:
          type: integer
          nullable: true
          description: Statut HTTP renvoyé par la destination du webhook, si disponible.
        error_message:
          type: string
          nullable: true
          description: Message d’erreur de livraison, si disponible.
        response_body_preview:
          type: string
          nullable: true
          description: >-
            Aperçu du corps de réponse de la destination du webhook avec données
            sensibles masquées.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Authentification par jeton Bearer

````

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