> ## 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 un lot

> Crée une tâche asynchrone par lots et renvoie l’objet de lot du fournisseur. La création prend en charge OpenAI, Anthropic, Google Gemini, Mistral, xAI, Groq et Together AI via le `model` demandé. La passerelle déduit le fournisseur à partir du modèle et accepte aussi `session_id` et `webhook` pour l’observabilité et les notifications asynchrones. Utilisez `provider` uniquement comme contrainte avancée de routage.

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 /batches
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:
  /batches:
    post:
      tags:
        - Gateway
      summary: Créer un lot
      description: >-
        Crée une tâche asynchrone par lots et renvoie l’objet de lot du
        fournisseur. La création prend en charge OpenAI, Anthropic, Google
        Gemini, Mistral, xAI, Groq et Together AI via le `model` demandé. La
        passerelle déduit le fournisseur à partir du modèle et accepte aussi
        `session_id` et `webhook` pour l’observabilité et les notifications
        asynchrones. Utilisez `provider` uniquement comme contrainte avancée de
        routage.
      operationId: createBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Réponse d’état du lot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '401':
          description: Non autorisé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    BatchRequest:
      type: object
      properties:
        provider_options:
          type: object
          description: >-
            Extensions limitées par ID canonique du fournisseur. OpenAI accepte
            output_expires_after ; Mistral accepte metadata. Seules les options
            du fournisseur choisi s’appliquent. Ne dupliquez pas une option au
            premier niveau. Les options ne peuvent pas remplacer les lignes
            tarifées, modèles ou fichiers.
          additionalProperties:
            type: object
            additionalProperties: true
        model:
          type: string
          description: >-
            ID du modèle utilisé pour déduire le fournisseur du lot. Les lignes
            de requête peuvent aussi inclure body.model ; le modèle de premier
            niveau est prioritaire.
        prompts:
          type: array
          description: >-
            Format abrégé de prompt simple. Phaseo compile chaque prompt en
            ligne de lot native du fournisseur pour le modèle choisi.
          items:
            type: string
        items:
          type: array
          description: >-
            Format abrégé de prompt structuré. Les éléments peuvent inclure
            `id`, `custom_id`, `prompt`, `messages`, `input`, `system`,
            `max_tokens`, `temperature` ou un `body` avancé.
          items:
            type: object
            additionalProperties: true
        system:
          type: string
          description: >-
            Instruction système facultative appliquée aux lignes de prompts
            abrégés.
        max_tokens:
          type: integer
          description: >-
            Limite maximale facultative de tokens appliquée aux lignes de
            prompts abrégés.
        temperature:
          type: number
          description: >-
            Température d’échantillonnage facultative appliquée aux lignes de
            prompts abrégés.
        input_file_id:
          type: string
          description: >-
            ID d’un fichier existant du fournisseur pour créer un lot par
            téléversement de fichier.
        requests:
          type: array
          description: >-
            Lignes avancées de requêtes par lots. Fournissez exactement un champ
            parmi `prompts`, `items`, `requests` et `input_file_id`.
          items:
            $ref: '#/components/schemas/BatchRequestItem'
        endpoint:
          type: string
          enum:
            - /v1/chat/completions
            - /v1/responses
            - /v1/messages
            - /v1/embeddings
            - /v1/generateContent
          description: >-
            Format de requête côté client. Toutes les requêtes d’un lot
            utilisent cet endpoint. Si omis, Phaseo choisit une valeur par
            défaut native du fournisseur selon le modèle.
        completion_window:
          type: string
        metadata:
          type: object
          additionalProperties: true
        session_id:
          type: string
          maxLength: 256
          description: >-
            Identifiant unique permettant de regrouper des requêtes liées (par
            exemple, une conversation ou un flux de travail d’agent) à des fins
            d’observabilité.
        webhook:
          type: object
          required:
            - endpoint_id
          additionalProperties: false
          properties:
            endpoint_id:
              type: string
              description: ID d’endpoint webhook géré par l’espace de travail.
            events:
              type: array
              description: >-
                Abonnements facultatifs aux événements. Utilisez les événements
                génériques job.* ou les événements batch.* correspondants, par
                exemple batch.progress ou batch.completed. Par défaut, les
                événements finaux job.* sont utilisés. Incluez explicitement
                job.progress ou batch.progress pour les callbacks de progression
                du nombre de requêtes. Si la liste est fournie, au moins un
                événement doit être valide pour les tâches par lots ; les listes
                mal formées ou ne contenant que des événements d’un autre type
                sont rejetées.
              items:
                type: string
        webhook_endpoint_id:
          type: string
          description: Alias pratique de webhook.endpoint_id.
        debug:
          $ref: '#/components/schemas/DebugOptions'
        provider:
          allOf:
            - $ref: '#/components/schemas/ProviderRoutingOptions'
          description: >-
            Contrainte avancée de routage. La plupart des requêtes devraient se
            fier à la déduction du fournisseur à partir du modèle.
    BatchResponse:
      type: object
      properties:
        id:
          type: string
        native_batch_id:
          type: string
          nullable: true
          description: >-
            ID de lot natif du fournisseur lorsqu’il diffère de l’ID de la
            passerelle.
        object:
          type: string
        endpoint:
          type: string
        errors:
          type: object
        input_file_id:
          type: string
        completion_window:
          type: string
        status:
          type: string
        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.
        progress:
          type: integer
          minimum: 0
          maximum: 100
          description: >-
            Pourcentage approximatif d’achèvement du lot calculé à partir des
            nombres de requêtes du fournisseur, si disponibles. Les lots
            terminés indiquent 100.
        polling_url:
          type: string
          format: uri
        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.
        cancel_url:
          type: string
          format: uri
          nullable: true
          description: Réservé à la compatibilité ; actuellement toujours null.
        results_url:
          type: string
          format: uri
          nullable: true
          description: >-
            URL authentifiée de téléchargement JSONL Phaseo pour les lots pris
            en charge dans un état final. Null pendant le traitement. Un lot
            final peut ne produire aucune sortie. Utilisez une clé API de
            l’espace de travail propriétaire ; les limites de conservation du
            fournisseur s’appliquent.
        output_file_id:
          type: string
        error_file_id:
          type: string
        created_at:
          type: integer
        in_progress_at:
          type: integer
        expires_at:
          type: integer
        finalizing_at:
          type: integer
        completed_at:
          type: integer
        failed_at:
          type: integer
        expired_at:
          type: integer
        cancelling_at:
          type: integer
        cancelled_at:
          type: integer
        request_counts:
          $ref: '#/components/schemas/BatchRequestCounts'
        metadata:
          type: object
        request_id:
          type: string
        provider:
          type: string
        session_id:
          type: string
        webhook:
          $ref: '#/components/schemas/AsyncWebhookPublicState'
        next_webhook_retry_at:
          type: string
          nullable: true
        last_webhook_progress:
          type: number
          nullable: true
        last_webhook_progress_at:
          type: string
          nullable: true
        last_webhook_dispatched_at:
          type: string
          nullable: true
        finalized_at:
          type: string
          nullable: true
        pricing_lines:
          type: array
          items:
            type: object
            additionalProperties: true
        usage:
          type: object
          description: Consommation et coût agrégés normalisés après finalisation.
          properties:
            requests:
              type: integer
              nullable: true
            input_tokens:
              type: integer
              nullable: true
            output_tokens:
              type: integer
              nullable: true
            total_tokens:
              type: integer
              nullable: true
            cost_nanos:
              type: integer
              nullable: true
            cost_usd:
              type: number
              nullable: true
            currency:
              type: string
        billing:
          $ref: '#/components/schemas/BatchBillingSummary'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        ok:
          type: boolean
          example: false
        error:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
          example: error_type
        message:
          type: string
          example: Human-readable error message
        description:
          type: string
          example: Additional error details.
        generation_id:
          type: string
          example: G-abc123
        status_code:
          type: integer
          example: 502
        error_type:
          type: string
          enum:
            - user
            - system
          example: system
        error_origin:
          type: string
          enum:
            - user
            - gateway
            - upstream
          example: upstream
        reason:
          type: string
          example: all_candidates_failed
        attempt_count:
          type: integer
          example: 2
        failed_providers:
          type: array
          items:
            type: string
          example:
            - google-ai-studio
            - openai
        failed_statuses:
          type: array
          items:
            type: integer
          example:
            - 403
            - 429
        upstream_error:
          $ref: '#/components/schemas/ErrorUpstreamError'
        failure_sample:
          type: array
          items:
            $ref: '#/components/schemas/ErrorFailureSampleItem'
        provider_failure_diagnostics:
          $ref: '#/components/schemas/ErrorProviderFailureDiagnostics'
        routing_diagnostics:
          $ref: '#/components/schemas/ErrorRoutingDiagnostics'
        provider_candidate_diagnostics:
          $ref: '#/components/schemas/ErrorProviderCandidateDiagnostics'
        provider_enablement:
          $ref: '#/components/schemas/ErrorProviderEnablementDiagnostics'
        missing_pricing_providers:
          type: array
          items:
            type: string
        provider_payment_required_provider:
          type: string
          example: openai
        provider_payment_required_support_notice:
          type: string
          example: >-
            Our upstream provider billing appears to be unavailable. If this
            persists, contact support.
        details:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    BatchRequestItem:
      type: object
      required:
        - body
      properties:
        custom_id:
          type: string
        method:
          type: string
          default: POST
          enum:
            - POST
        url:
          type: string
          description: >-
            Chemin d’endpoint de cette ligne. S’il est fourni, il doit
            correspondre à l’endpoint du lot parent. Par défaut, l’endpoint du
            lot parent est utilisé.
        body:
          type: object
          additionalProperties: true
    DebugOptions:
      type: object
      description: >-
        Options de débogage de la passerelle. Ces indicateurs ne sont jamais
        transmis au fournisseur.
      properties:
        enabled:
          type: boolean
        return_upstream_request:
          type: boolean
        return_upstream_response:
          type: boolean
        trace:
          type: boolean
        trace_level:
          type: string
          enum:
            - summary
            - full
    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
    BatchRequestCounts:
      type: object
      properties:
        total:
          type: integer
        completed:
          type: integer
        failed:
          type: integer
    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'
    BatchBillingSummary:
      type: object
      properties:
        currency:
          type: string
        billed:
          type: boolean
        charged:
          type: boolean
        reason:
          type: string
        state:
          type: string
          enum:
            - pending
            - estimated
            - settled
            - void
        reservation_id:
          type: string
          nullable: true
        reservation_status:
          type: string
          nullable: true
        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
        estimated_nanos:
          type: integer
          nullable: true
        reserved_nanos:
          type: integer
          nullable: true
        estimation_truncated:
          type: boolean
          nullable: true
          description: >-
            True si l’estimation de réservation a été extrapolée à partir d’un
            échantillon limité d’un fichier d’entrée de lot plus grand.
        estimation_sample_size:
          type: integer
          nullable: true
          description: >-
            Nombre de lignes d’entrée tarifées directement pour l’estimation de
            réservation.
        estimation_total_rows:
          type: integer
          nullable: true
          description: >-
            Nombre total de lignes d’entrée représentées par l’estimation de
            réservation.
        total_nanos:
          type: integer
          nullable: true
        cost_nanos:
          type: integer
          nullable: true
        cost_usd:
          type: number
          nullable: true
        finalized_at:
          type: string
          nullable: true
        pricing_breakdown:
          type: object
          additionalProperties: true
    ErrorUpstreamError:
      type: object
      properties:
        code:
          type: string
          nullable: true
          example: PERMISSION_DENIED
        message:
          type: string
          nullable: true
          example: The caller does not have permission.
        description:
          type: string
          nullable: true
        param:
          type: string
          nullable: true
    ErrorFailureSampleItem:
      type: object
      properties:
        provider:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
        status:
          type: integer
          nullable: true
        upstream_error_code:
          type: string
          nullable: true
        upstream_error_message:
          type: string
          nullable: true
        upstream_error_description:
          type: string
          nullable: true
        upstream_error_param:
          type: string
          nullable: true
        upstream_payload_preview:
          type: string
          nullable: true
        retryable:
          type: boolean
          nullable: true
      additionalProperties: true
    ErrorProviderFailureDiagnostics:
      type: object
      properties:
        category:
          type: string
          enum:
            - credentials_not_configured
            - credentials_invalid_or_forbidden
            - provider_access_missing
            - region_or_project_restriction
            - model_unavailable_for_endpoint
            - rate_limited
            - server_error
        hint:
          type: string
        provider:
          type: string
          nullable: true
    ErrorRoutingDiagnostics:
      type: object
      properties:
        filterStages:
          type: array
          items:
            type: object
            properties:
              stage:
                type: string
              beforeCount:
                type: integer
              afterCount:
                type: integer
              droppedProviders:
                type: array
                items:
                  type: object
                  properties:
                    providerId:
                      type: string
                      nullable: true
                    reason:
                      type: string
                      nullable: true
                  additionalProperties: true
            additionalProperties: true
      additionalProperties: true
    ErrorProviderCandidateDiagnostics:
      type: object
      properties:
        totalProviders:
          type: integer
        supportsEndpointCount:
          type: integer
        candidateCount:
          type: integer
        droppedUnsupportedEndpoint:
          type: array
          items:
            type: string
        droppedMissingAdapter:
          type: array
          items:
            type: object
            properties:
              providerId:
                type: string
                nullable: true
              endpoint:
                type: string
                nullable: true
            additionalProperties: true
      additionalProperties: true
    ErrorProviderEnablementDiagnostics:
      type: object
      properties:
        capability:
          type: string
        providersBefore:
          type: array
          items:
            type: string
        providersAfter:
          type: array
          items:
            type: string
        dropped:
          type: array
          items:
            type: object
            properties:
              providerId:
                type: string
                nullable: true
              reason:
                type: string
                nullable: true
            additionalProperties: true
      additionalProperties: true
    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.