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

# إنشاء موسيقى

> ينشئ الموسيقى عبر endpoint واحد مستقل عن المزوّد. تنتظر Phaseo المزوّدين المتزامنين وتتولى داخليًا الاستعلام المتكرر عن قوائم انتظارهم.

إنشاء الموسيقى عبر واجهة API واحدة مستقلة عن المزوّد. ويتولى Phaseo معالجة الاستجابات المتزامنة واستطلاع قوائم انتظار المزوّدين في الخلفية.

عند اكتمال التوليد، تتضمن الاستجابة `audio_url` أو `audio_base64`. وإذا أعاد المزوّد مهمة غير نهائية، فاستخدم `id` نفسه من الاستجابة مع `GET /music/generate/{music_id}`.

## بنية الطلب

```json theme={null}
{
  "model": "minimax/music-3.0:free",
  "prompt": "Warm jazz trio with brushed drums",
  "format": "mp3"
}
```

## خيارات Suno

* `suno.customMode` (قيمة منطقية، الافتراضي `false`)
* `suno.instrumental` (قيمة منطقية، الافتراضي `false`)
* `suno.prompt` (تجاوز اختياري لـ `prompt` في المستوى الأعلى)
* `suno.style`, `suno.title` (مطلوب عندما تكون `customMode = true`)
* `suno.personaId`, `suno.personaModel`
* `suno.negativeTags`, `suno.vocalGender`
* `suno.styleWeight`, `suno.weirdnessConstraint`, `suno.audioWeight`

## قواعد التحقق

* عندما تكون `customMode = false`، يكون `prompt` مطلوبًا.
* عندما تكون `customMode = true`، يكون كل من `style` و`title` مطلوبًا.
* عندما تكون `customMode = true` و`instrumental = false`، يكون `prompt` مطلوبًا.

تعيد أخطاء التحقق `400` مع:

```json theme={null}
{
  "error": "validation_error",
  "reason": "..."
}
```

## الاستجابة

```json theme={null}
{
  "id": "req_01JY6MUSIC123",
  "object": "music",
  "status": "completed",
  "provider": "gmicloud",
  "model": "minimax/music-3.0:free",
  "nativeResponseId": "5c30b275-d669-4a25-8151-de6d60214853",
  "audio_url": "https://.../generated-music.mp3",
  "usage": {
    "requests": 1,
    "output_audio_seconds": 25.364
  }
}
```

* `id` هو معرّف طلب Phaseo الثابت. استخدمه لاسترجاع الطلب عبر `GET /music/generate/{music_id}`.
* `nativeResponseId` هو معرّف مزود الخدمة الأصلي، ويُستخدم لربط الطلب بالمزود وطلب الدعم منه.
* يمكن أن تكون قيمة `status` هي `queued` أو `in_progress` أو `completed` أو `failed`.
* قد يتضمن `usage` الحقل `output_audio_seconds` عندما يبلغ المزود عن مدة الصوت المُنشأ.


## OpenAPI

````yaml ar/openapi/v1/openapi.localized.yaml POST /music/generate
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:
  /music/generate:
    post:
      tags:
        - Gateway
      summary: إنشاء موسيقى
      description: >-
        ينشئ الموسيقى عبر endpoint واحد مستقل عن المزوّد. تنتظر Phaseo المزوّدين
        المتزامنين وتتولى داخليًا الاستعلام المتكرر عن قوائم انتظارهم.
      operationId: generateMusic
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MusicGenerateRequest'
      responses:
        '200':
          description: استجابة إنشاء الموسيقى
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MusicGenerateResponse'
components:
  schemas:
    MusicGenerateRequest:
      type: object
      required:
        - model
      properties:
        model:
          type: string
        prompt:
          type: string
        duration:
          type: integer
        format:
          type: string
          enum:
            - mp3
            - wav
            - ogg
            - aac
        provider:
          $ref: '#/components/schemas/ProviderRoutingOptions'
        suno:
          type: object
          properties:
            prompt:
              type: string
            style:
              type: string
            title:
              type: string
            customMode:
              type: boolean
            instrumental:
              type: boolean
            personaId:
              type: string
            model:
              type: string
            negativeTags:
              type: string
            vocalGender:
              type: string
              enum:
                - m
                - f
            styleWeight:
              type: number
              minimum: 0
              maximum: 1
            weirdnessConstraint:
              type: number
              minimum: 0
              maximum: 1
            audioWeight:
              type: number
              minimum: 0
              maximum: 1
            callBackUrl:
              type: string
              format: uri
        elevenlabs:
          type: object
          properties:
            prompt:
              type: string
            composition_plan:
              type: object
            music_length_ms:
              type: integer
            model_id:
              type: string
            force_instrumental:
              type: boolean
            store_for_inpainting:
              type: boolean
            with_timestamps:
              type: boolean
            sign_with_c2pa:
              type: boolean
            output_format:
              type: string
        echo_upstream_request:
          type: boolean
        debug:
          $ref: '#/components/schemas/DebugOptions'
    MusicGenerateResponse:
      type: object
      required:
        - id
        - object
        - status
        - model
        - provider
      properties:
        id:
          type: string
          description: معرّف طلب ثابت من Phaseo يُستخدم مع GET /music/generate/{music_id}.
        object:
          type: string
          enum:
            - music
        status:
          type: string
          enum:
            - queued
            - in_progress
            - completed
            - failed
        model:
          type: string
        provider:
          type: string
        nativeResponseId:
          type: string
          nullable: true
          description: معرّف المزوّد upstream لأغراض الربط والدعم.
        audio_url:
          type: string
          format: uri
        audio_base64:
          type: string
        result:
          description: بيانات وصفية لنتيجة المزوّد بعد توحيدها بواسطة Phaseo.
        output:
          type: array
          items:
            type: object
            additionalProperties: true
        usage:
          type: object
          additionalProperties: true
      additionalProperties: true
    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
    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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: المصادقة باستخدام رمز Bearer

````

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