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

# إنشاء دفعة

> ينشئ مهمة دفعة غير متزامنة ويرجع كائن الدفعة لدى المزوّد الأعلى. يدعم الإنشاء OpenAI وAnthropic وGoogle Gemini وMistral وxAI وGroq وTogether AI عبر `model` المطلوب. تستنتج البوابة المزوّد من النموذج وتقبل أيضاً `session_id` و`webhook` لقابلية الرصد والإشعارات غير المتزامنة. استخدم `provider` فقط كقيد توجيه متقدم.

يتطلب الوصول إلى الميزات التجريبية في مساحة العمل. راجع [مهام الفيديو والمعالجة على دفعات](../../guides/async-video-and-batch.mdx) لمعرفة الإعداد والويب هوك والتعامل مع النتائج.


## OpenAPI

````yaml ar/openapi/v1/openapi.localized.yaml POST /batches
openapi: 3.0.3
info:
  title: Phaseo Gateway API
  description: >-
    واجهة API للبوابة تتيح الوصول إلى نماذج ذكاء اصطناعي متنوعة عبر نقاط نهاية
    متوافقة مع OpenAI.
  version: 1.0.0
  contact:
    name: Phaseo
    url: https://phaseo.app
    email: danielbutler500@gmail.com
servers:
  - url: https://api.phaseo.app/v1
    description: التوجيه العالمي
security:
  - BearerAuth: []
tags:
  - name: Gateway
    description: Core Phaseo Gateway operations.
paths:
  /batches:
    post:
      tags:
        - Gateway
      summary: إنشاء دفعة
      description: >-
        ينشئ مهمة دفعة غير متزامنة ويرجع كائن الدفعة لدى المزوّد الأعلى. يدعم
        الإنشاء OpenAI وAnthropic وGoogle Gemini وMistral وxAI وGroq وTogether
        AI عبر `model` المطلوب. تستنتج البوابة المزوّد من النموذج وتقبل أيضاً
        `session_id` و`webhook` لقابلية الرصد والإشعارات غير المتزامنة. استخدم
        `provider` فقط كقيد توجيه متقدم.
      operationId: createBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: استجابة حالة الدفعة
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '401':
          description: غير مصرّح به
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    BatchRequest:
      type: object
      properties:
        provider_options:
          type: object
          description: >-
            امتدادات محددة بمعرّف المزوّد الأساسي. يقبل OpenAI الحقل
            output_expires_after ويقبل Mistral الحقل metadata. تُطبق خيارات
            المزوّد المحدد فقط. لا تكرر خياراً في المستوى الأعلى. لا يمكن
            للخيارات تجاوز الصفوف المُسعّرة أو النماذج أو الملفات.
          additionalProperties:
            type: object
            additionalProperties: true
        model:
          type: string
          description: >-
            معرّف النموذج المستخدم لاستنتاج مزوّد الدفعة الأعلى. قد تتضمن صفوف
            الطلب أيضاً body.model؛ ويُفضّل النموذج في المستوى الأعلى.
        prompts:
          type: array
          description: >-
            صيغة مختصرة لموجه بسيط. يحوّل Phaseo كل موجه إلى صف دفعة أصلي لدى
            المزوّد للنموذج المحدد.
          items:
            type: string
        items:
          type: array
          description: >-
            صيغة مختصرة لموجه منظم. قد تتضمن العناصر `id` و`custom_id` و`prompt`
            و`messages` و`input` و`system` و`max_tokens` و`temperature` أو`body`
            متقدماً.
          items:
            type: object
            additionalProperties: true
        system:
          type: string
          description: تعليمة نظام اختيارية تُطبق على صفوف الموجهات المختصرة.
        max_tokens:
          type: integer
          description: حد أقصى اختياري للرموز يُطبق على صفوف الموجهات المختصرة.
        temperature:
          type: number
          description: درجة حرارة أخذ عينات اختيارية تُطبق على صفوف الموجهات المختصرة.
        input_file_id:
          type: string
          description: معرّف ملف موجود لدى المزوّد لإنشاء دفعة عبر رفع ملف.
        requests:
          type: array
          description: >-
            صفوف طلبات دفعات متقدمة. قدم واحداً فقط من `prompts` أو`items`
            أو`requests` أو`input_file_id`.
          items:
            $ref: '#/components/schemas/BatchRequestItem'
        endpoint:
          type: string
          enum:
            - /v1/chat/completions
            - /v1/responses
            - /v1/messages
            - /v1/embeddings
            - /v1/generateContent
          description: >-
            صيغة الطلب الموجهة للمستدعي. يستخدم كل طلب في الدفعة نقطة النهاية
            هذه. عند الإغفال يختار Phaseo قيمة افتراضية أصلية لدى المزوّد بناءً
            على النموذج.
        completion_window:
          type: string
        metadata:
          type: object
          additionalProperties: true
        session_id:
          type: string
          maxLength: 256
          description: >-
            معرّف فريد لتجميع الطلبات المرتبطة (مثل محادثة أو سير عمل وكيل)
            لأغراض قابلية المراقبة.
        webhook:
          type: object
          required:
            - endpoint_id
          additionalProperties: false
          properties:
            endpoint_id:
              type: string
              description: معرّف نقطة نهاية webhook التي تديرها مساحة العمل.
            events:
              type: array
              description: >-
                اشتراكات اختيارية في الأحداث. استخدم أحداث job.* العامة أو أحداث
                batch.* المطابقة، مثل batch.progress أوbatch.completed. عند
                الإغفال تُستخدم أحداث job.* النهائية. أدرج job.progress
                أوbatch.progress صراحةً لردود اتصال تقدم عدد الطلبات. عند توفير
                القائمة يجب أن يكون حدث واحد على الأقل صالحاً لمهام الدفعات؛
                تُرفض القوائم غير الصحيحة أو التي تحتوي فقط على أحداث من نوع
                آخر.
              items:
                type: string
        webhook_endpoint_id:
          type: string
          description: اسم بديل ملائم لـwebhook.endpoint_id.
        debug:
          $ref: '#/components/schemas/DebugOptions'
        provider:
          allOf:
            - $ref: '#/components/schemas/ProviderRoutingOptions'
          description: >-
            قيد توجيه متقدم. ينبغي لمعظم الطلبات الاعتماد على استنتاج المزوّد
            بناءً على النموذج.
    BatchResponse:
      type: object
      properties:
        id:
          type: string
        native_batch_id:
          type: string
          nullable: true
          description: معرّف الدفعة الأصلي لدى المزوّد عندما يختلف عن معرّف البوابة.
        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: >-
            حالة دورة الحياة غير المتزامنة الموحدة لمستهلكي الاستطلاع وWebSocket
            وwebhook.
        progress:
          type: integer
          minimum: 0
          maximum: 100
          description: >-
            نسبة إكمال تقريبية للدفعة مشتقة من أعداد طلبات المزوّد عند توفرها.
            تبلغ الدفعات المكتملة عن 100.
        polling_url:
          type: string
          format: uri
        websocket_url:
          type: string
          format: uri
          description: >-
            عنوان WebSocket للاشتراك في تحديثات دورة الحياة الموحدة للمهام غير
            المتزامنة.
        cancel_url:
          type: string
          format: uri
          nullable: true
          description: محجوز للتوافق؛ قيمته حالياً null دائماً.
        results_url:
          type: string
          format: uri
          nullable: true
          description: >-
            عنوان تنزيل Phaseo JSONL يتطلب المصادقة للدفعات المدعومة في حالة
            نهائية. يكون null أثناء المعالجة. قد لا يكون للدفعة النهائية ناتج.
            استخدم مفتاح API من مساحة العمل المالكة؛ تنطبق حدود الاحتفاظ لدى
            المزوّد.
        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: الاستخدام والتكلفة الإجمالية الموحدة بعد الإنهاء.
          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: >-
            مسار نقطة النهاية لهذا الصف. عند توفيره يجب أن يطابق نقطة نهاية
            الدفعة الأصلية. القيمة الافتراضية هي نقطة نهاية الدفعة الأصلية.
        body:
          type: object
          additionalProperties: true
    DebugOptions:
      type: object
      description: >-
        عناصر تحكم تصحيح أخطاء البوابة. لا تُمرر هذه العلامات إلى المزوّد
        مطلقًا.
      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: تفضيلات توجيه المزوّد لاختياره عبر البوابة.
      properties:
        order:
          type: array
          items:
            type: string
        only:
          type: array
          items:
            type: string
        ignore:
          type: array
          items:
            type: string
        include_alpha:
          type: boolean
          description: تضمين مزوّدي alpha في التوجيه (معطّل افتراضيًا).
        allow_fallbacks:
          type: boolean
          nullable: true
          description: السماح بالتحويل إلى مزوّد مؤهل آخر بعد الفشل.
        require_parameters:
          type: boolean
          nullable: true
          description: اشتراط دعم المزوّد للمعلمات المطلوبة قبل التوجيه.
        required_execution_region:
          type: string
          nullable: true
          description: قصر التوجيه على المزوّدين الذين لديهم منطقة التنفيذ المطلوبة.
        required_data_region:
          type: string
          nullable: true
          description: قصر التوجيه على المزوّدين الذين لديهم منطقة البيانات المطلوبة.
        require_zero_data_retention:
          type: boolean
          nullable: true
          description: >-
            قصر التوجيه على المزوّدين الذين يدعمون الاحتفاظ بالبيانات لمدة
            صفرية.
        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: >-
            رتّب المزوّدين لهذا الطلب، مثلاً حسب السعر أو زمن الاستجابة أو معدل
            النقل.
        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: >-
        إعداد webhook غير المتزامن بعد تنقيح البيانات الحساسة مع حالة التسليم.
        لا تُرجع الأسرار أبداً؛ يشير `has_secret` إلى تفعيل عمليات التسليم
        الموقّعة. تتضمن عمليات التسليم الموقّعة ترويسات x-phaseo-signature
        وx-phaseo-timestamp وx-phaseo-event-id وx-phaseo-event-type
        وx-phaseo-delivery-key وx-phaseo-attempt و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 عندما يُوسّع تقدير الحجز من عينة محدودة لملف إدخال دفعة
            أكبر.
        estimation_sample_size:
          type: integer
          nullable: true
          description: عدد صفوف الإدخال التي سُعّرت مباشرةً لتقدير الحجز.
        estimation_total_rows:
          type: integer
          nullable: true
          description: إجمالي صفوف الإدخال التي يمثلها تقدير الحجز.
        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: >-
        ملخص تسليم عام لخطافات webhook غير المتزامنة التي تديرها البوابة.
        استخدمه للتمييز بين حالة تنفيذ المهمة وسلامة تسليم webhook.
      properties:
        total_attempts:
          type: integer
          description: إجمالي محاولات التسليم المسجلة لهذه المهمة.
        delivered_events:
          type: integer
          description: عدد مفاتيح التسليم التي وصلت إلى حالة التسليم الناجح.
        delivered_event_types:
          type: array
          description: مفاتيح التسليم التي سُلّمت مرة واحدة على الأقل.
          items:
            type: string
          example:
            - video.completed
        pending_retries:
          type: integer
          description: عدد مفاتيح التسليم المجدولة حالياً لإعادة المحاولة.
        next_retry_at:
          type: string
          nullable: true
          description: طابع ISO الزمني لإعادة المحاولة المجدولة التالية، إن وجد.
        last_attempt_at:
          type: string
          nullable: true
          description: طابع ISO الزمني لأحدث محاولة تسليم.
        last_attempt_status:
          type: string
          nullable: true
          enum:
            - delivered
            - scheduled_retry
            - failed_permanently
          description: نتيجة أحدث محاولة تسليم.
        last_response_status:
          type: integer
          nullable: true
          description: حالة HTTP التي ترجعها وجهة webhook، إن توفرت.
        last_delivered_at:
          type: string
          nullable: true
          description: طابع ISO الزمني لأحدث تسليم ناجح.
        last_failure_at:
          type: string
          nullable: true
          description: طابع ISO الزمني لأحدث محاولة فاشلة أو قيد إعادة المحاولة.
        last_error_message:
          type: string
          nullable: true
          description: أحدث رسالة خطأ في التسليم، إن توفرت.
    AsyncWebhookDeliveryAttempt:
      type: object
      description: محاولة تسليم حديثة لخطاف webhook غير متزامن تديره البوابة.
      properties:
        id:
          type: string
          description: معرّف ثابت للمحاولة لأغراض التدقيق وتصحيح الأخطاء.
        delivery_key:
          type: string
          description: مفتاح عدم تكرار الأثر لتسليم هذا الحدث.
          example: video.completed
        event_type:
          type: string
          description: نوع الحدث الذي سُلّم إلى وجهة webhook.
          example: video.completed
        status:
          type: string
          enum:
            - delivered
            - scheduled_retry
            - failed_permanently
        attempt_number:
          type: integer
          description: رقم المحاولة لمفتاح التسليم هذا، بدءاً من واحد.
        max_attempts:
          type: integer
          description: الحد الأقصى للمحاولات قبل وضع علامة فشل دائم على التسليم.
        tried_at:
          type: string
          description: طابع ISO الزمني عند إجراء هذه المحاولة.
        delivered_at:
          type: string
          nullable: true
          description: طابع ISO الزمني عند نجاح تسليم هذه المحاولة.
        next_retry_at:
          type: string
          nullable: true
          description: طابع ISO الزمني لإعادة المحاولة التالية بعد هذه المحاولة، إن جُدولت.
        response_status:
          type: integer
          nullable: true
          description: حالة HTTP التي ترجعها وجهة webhook، إن توفرت.
        error_message:
          type: string
          nullable: true
          description: رسالة خطأ التسليم، إن توفرت.
        response_body_preview:
          type: string
          nullable: true
          description: معاينة منقحة من البيانات الحساسة لجسم استجابة وجهة webhook.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: المصادقة باستخدام رمز Bearer

````

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