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

# إنشاء فيديو

> ينشئ مهمة إنشاء فيديو غير متزامنة. استعلم عن `polling_url` المُرجع كل 20 ثانية حتى تصل المهمة إلى حالة نهائية.

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


## OpenAPI

````yaml ar/openapi/v1/openapi.localized.yaml POST /videos
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:
  /videos:
    post:
      tags:
        - Gateway
      summary: إنشاء فيديو
      description: >-
        ينشئ مهمة إنشاء فيديو غير متزامنة. استعلم عن `polling_url` المُرجع كل 20
        ثانية حتى تصل المهمة إلى حالة نهائية.
      operationId: createVideo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoGenerationRequest'
      responses:
        '202':
          description: استجابة الفيديو
          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: المدة المطلوبة بالثواني (تعتمد على المزوّد/النموذج).
        input_video_duration:
          type: number
          format: double
          minimum: 0
          maximum: 3600
          exclusiveMinimum: true
          description: >-
            مدة الفيديو المصدر بالثواني. مطلوبة عندما يفوتر المزوّد مدة الفيديو
            المصدر بشكل مستقل عن الناتج المُنشأ.
        input_audio_duration:
          type: number
          format: double
          minimum: 2
          maximum: 20
          description: >-
            مدة الصوت المصدر المعلنة بالثواني، المستخدمة للتحقق من نطاق المزوّد.
            قد يفوتر المزوّدون الذين لا يبلغون عن الاستخدام المعتمد وفق الحد
            الأعلى لمدة الإدخال المدعومة لديهم.
        size:
          type: string
          description: >-
            أبعاد صريحة (مثل 1280x720). لا يمكن دمجها مع resolution أو
            aspect_ratio.
        resolution:
          type: string
          description: >-
            480p و720p و1080p و1K و2K و4K. يمكن دمجها مع aspect_ratio. لا يمكن
            دمجها مع size.
        aspect_ratio:
          type: string
          description: >-
            نسبة أبعاد مثل 16:9 أو9:16 أو1:1. يمكن دمجها مع resolution. لا يمكن
            دمجها مع size.
        seed:
          type: integer
        sample_count:
          type: integer
          minimum: 1
          maximum: 4
        negative_prompt:
          type: string
        generate_audio:
          type: boolean
        enhance_prompt:
          type: boolean
        compression_quality:
          type: integer
        person_generation:
          type: string
        resize_mode:
          type: string
        input_references:
          type: array
          description: >-
            مدخلات صور أو صوت أو فيديو عبر HTTPS لتوجيه الإنشاء. تعتمد الأنواع
            والأدوار والأعداد والتركيبات المدعومة على النموذج المحدد. تحقق من
            GET /videos/models قبل إرسال مهمة. يقبل الاسم البديل المفرد للتوافق
            input_reference، غير المدرج في هذا المخطط، صورة multipart أو كائناً
            يتضمن واحداً فقط من file_id أو image_url. يعتمد الدعم على المزوّد.
          items:
            $ref: '#/components/schemas/VideoInputReference'
        frame_images:
          type: array
          minItems: 1
          maxItems: 2
          description: >-
            صور HTTPS للإطار الأول/الأخير. يمكن أن يظهر كل frame_type مرة واحدة.
            لا تقدم أيضاً input_reference أو أدوار الإطارات ضمن
            input_references.
          items:
            type: object
            additionalProperties: false
            required:
              - type
              - frame_type
              - image_url
            properties:
              type:
                type: string
                enum:
                  - image_url
              frame_type:
                type: string
                enum:
                  - first_frame
                  - last_frame
              image_url:
                type: object
                required:
                  - url
                properties:
                  url:
                    type: string
                    format: uri
        provider_params:
          type: object
          additionalProperties: true
          description: >-
            امتدادات خاصة بالمزوّد فقط. يُرفض تمرير الطلب كاملاً وتكرار حقول
            التوجيه أو الموجه أو رد الاتصال أو الفوترة.
        provider_options:
          type: object
          additionalProperties:
            type: object
            additionalProperties: true
          description: >-
            امتدادات بمفاتيح معرّفات المزوّدين الأساسية (مثل atlascloud أو
            byteplus). تُمرر خيارات المزوّد المحدد فقط. لا يمكن دمجها مع
            provider_params. يجب أن تستخدم حقول التوجيه والموجه ورد الاتصال
            والمدة والدقة وعدد النواتج حقول المستوى الأعلى التي تم التحقق منها.
        output:
          $ref: '#/components/schemas/VideoOutputConfig'
        webhook:
          type: object
          required:
            - endpoint_id
          additionalProperties: false
          properties:
            endpoint_id:
              type: string
              description: >-
                نقطة نهاية webhook نشطة تديرها مساحة العمل. لا يُخزن سر التوقيع
                المشفر والقابل للتدوير في بيانات مهمة الفيديو الوصفية أبداً.
            events:
              type: array
              description: >-
                اشتراكات اختيارية في الأحداث. استخدم أحداث job.* العامة أو أحداث
                video.* المطابقة، مثل video.status_changed أوvideo.progress
                أوvideo.completed. عند الإغفال تُستخدم job.status_changed وأحداث
                job.* النهائية. أدرج job.progress أوvideo.progress صراحةً لردود
                اتصال التقدم. عند توفير القائمة يجب أن يكون حدث واحد على الأقل
                صالحاً لمهام الفيديو؛ تُرفض القوائم غير الصحيحة أو التي تحتوي
                فقط على أحداث من نوع آخر.
              items:
                type: string
        provider:
          $ref: '#/components/schemas/ProviderRoutingOptions'
    VideoGenerationResponse:
      type: object
      properties:
        id:
          type: string
        polling_url:
          type: string
        websocket_url:
          type: string
          format: uri
          description: >-
            عنوان WebSocket للاشتراك في تحديثات دورة الحياة الموحدة للمهام غير
            المتزامنة.
        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: >-
            حالة دورة الحياة غير المتزامنة الموحدة لمستهلكي الاستطلاع وWebSocket
            وwebhook.
        cancel_url:
          type: string
          format: uri
          nullable: true
          description: محجوز للتوافق؛ قيمته حالياً null دائماً.
        output_access:
          type: string
          enum:
            - bytes
            - signed_url
            - both
        generation_id:
          type: string
          nullable: true
        native_video_id:
          type: string
          nullable: true
          description: >-
            معرّف الفيديو/المهمة الأصلي لدى المزوّد عندما يختلف عن معرّف
            البوابة.
        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: >-
            موجود عندما يتضمن output_access القيمة bytes (نقطة نهاية تتطلب
            المصادقة).
        download_url:
          type: string
          nullable: true
          description: >-
            عنوان URL موقّع من الطرف الأول للتنزيل المباشر عندما تكون الحالة
            completed.
        expires_at:
          type: integer
          nullable: true
          description: طابع Unix الزمني (بالثواني) لانتهاء صلاحية download_url الموقّع.
        progress:
          type: integer
          nullable: true
        progress_source:
          type: string
        asset:
          type: object
          nullable: true
          properties:
            id:
              type: string
            mime_type:
              type: string
            bytes:
              type: integer
            sha256:
              type: string
            width:
              type: integer
            height:
              type: integer
            duration_seconds:
              type: number
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/VideoOutput'
        billing:
          $ref: '#/components/schemas/VideoBillingSummary'
        webhook:
          $ref: '#/components/schemas/AsyncWebhookPublicState'
        next_webhook_retry_at:
          type: string
          nullable: true
          description: >-
            طابع ISO الزمني لإعادة محاولة webhook المستخدم المجدولة التالية، إن
            كانت في قائمة الانتظار.
        last_webhook_progress:
          type: number
          nullable: true
          description: أحدث فئة تقدم تقريبية أُرسلت إلى مستهلكي webhook.
        last_webhook_progress_at:
          type: string
          nullable: true
          description: طابع ISO الزمني عند إرسال أحدث فئة تقدم لـwebhook.
        last_webhook_dispatched_at:
          type: string
          nullable: true
          description: طابع ISO الزمني لأحدث محاولة إرسال webhook.
        usage:
          type: object
          properties:
            cost:
              type: number
            is_byok:
              type: boolean
          additionalProperties: true
        error:
          nullable: true
    VideoInputReference:
      description: >-
        مدخل وسائط HTTPS محدد النوع. استخدم image_url للصور وmedia_url للصوت أو
        الفيديو. تصف الأدوار كيفية استخدام النموذج للمدخل؛ ويختلف الدعم حسب
        المزوّد والنموذج.
      oneOf:
        - type: object
          required:
            - type
            - image_url
          properties:
            type:
              type: string
              enum:
                - image_url
            role:
              type: string
              description: الاستخدام المقصود لهذه الصورة من قِبل النموذج المحدد.
              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: عنوان HTTPS لصورة متاحة للعامة.
        - type: object
          required:
            - type
            - media_url
          properties:
            type:
              type: string
              enum:
                - video_url
                - audio_url
            role:
              type: string
              description: الاستخدام المقصود لهذا الصوت أو الفيديو من قِبل النموذج المحدد.
              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: عنوان HTTPS لصوت أو فيديو متاح للعامة.
    VideoOutputConfig:
      type: object
      properties:
        access:
          type: string
          enum:
            - bytes
            - signed_url
            - both
          default: both
          description: >-
            bytes=عنوان content_url الذي يتطلب المصادقة فقط، signed_url=روابط
            التنزيل الموقّعة فقط، both=تضمين الاثنين.
    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
    VideoOutput:
      type: object
      properties:
        index:
          type: integer
        mime_type:
          type: string
        bytes_available:
          type: boolean
        content_url:
          type: string
          description: موجود عندما يتضمن output_access القيمة bytes.
        download_url:
          type: string
          description: عنوان URL موقّع من الطرف الأول لهذا الناتج.
        expires_at:
          type: integer
          description: طابع Unix الزمني (بالثواني) لانتهاء صلاحية عنوان URL لهذا الناتج.
    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: >-
        إعداد 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'
    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.