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

# Musik generieren

> Erzeugt Musik über einen einzelnen anbieterunabhängigen Endpoint. Phaseo wartet auf synchrone Anbieter und übernimmt die Abfrage ihrer Warteschlangen intern.

Musik lässt sich über eine anbieterunabhängige API erzeugen. Phaseo verarbeitet synchrone Antworten und fragt Anbieterwarteschlangen im Hintergrund ab.

Nach Abschluss enthält die Antwort `audio_url` oder `audio_base64`. Gibt ein Anbieter einen noch nicht abgeschlossenen Auftrag zurück, verwende dieselbe Antwort-`id` mit `GET /music/generate/{music_id}`.

## Aufbau der Anfrage

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

## Suno-Optionen

* `suno.customMode` (boolesch, Standard: `false`)
* `suno.instrumental` (boolesch, Standard: `false`)
* `suno.prompt` (optionale Überschreibung von `prompt` auf oberster Ebene)
* `suno.style`, `suno.title` (erforderlich, wenn `customMode = true` ist)
* `suno.personaId`, `suno.personaModel`
* `suno.negativeTags`, `suno.vocalGender`
* `suno.styleWeight`, `suno.weirdnessConstraint`, `suno.audioWeight`

## Validierungsregeln

* Wenn `customMode = false` ist, ist `prompt` erforderlich.
* Wenn `customMode = true` ist, sind `style` und `title` erforderlich.
* Wenn `customMode = true` und `instrumental = false` sind, ist `prompt` erforderlich.

Validierungsfehler geben `400` zurück mit:

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

## Antwort

```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` ist die stabile Phaseo-Anfrage-ID. Verwenden Sie sie, um die Anfrage über `GET /music/generate/{music_id}` abzurufen.
* `nativeResponseId` ist die Kennung des vorgelagerten Anbieters und dient der Zuordnung beim Anbieter sowie für Supportanfragen.
* `status` kann `queued`, `in_progress`, `completed` oder `failed` sein.
* `usage` kann `output_audio_seconds` enthalten, wenn der Anbieter die erzeugte Dauer meldet.


## OpenAPI

````yaml de/openapi/v1/openapi.localized.yaml POST /music/generate
openapi: 3.0.3
info:
  title: Phaseo Gateway API
  description: >-
    Eine Gateway-API für den Zugriff auf verschiedene KI-Modelle über
    OpenAI-kompatible Endpunkte.
  version: 1.0.0
  contact:
    name: Phaseo
    url: https://phaseo.app
    email: danielbutler500@gmail.com
servers:
  - url: https://api.phaseo.app/v1
    description: Globales Routing
security:
  - BearerAuth: []
tags:
  - name: Gateway
    description: Core Phaseo Gateway operations.
paths:
  /music/generate:
    post:
      tags:
        - Gateway
      summary: Musik erzeugen
      description: >-
        Erzeugt Musik über einen einzelnen anbieterunabhängigen Endpoint. Phaseo
        wartet auf synchrone Anbieter und übernimmt die Abfrage ihrer
        Warteschlangen intern.
      operationId: generateMusic
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MusicGenerateRequest'
      responses:
        '200':
          description: Antwort zur Musikgenerierung
          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: >-
            Stabile Phaseo-Anfrage-ID für die Verwendung mit 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-Anbieterkennung für Korrelation und Support.
        audio_url:
          type: string
          format: uri
        audio_base64:
          type: string
        result:
          description: Von Phaseo normalisierte Metadaten des Anbieterergebnisses.
        output:
          type: array
          items:
            type: object
            additionalProperties: true
        usage:
          type: object
          additionalProperties: true
      additionalProperties: true
    ProviderRoutingOptions:
      type: object
      description: Anbieterrouting-Präferenzen für die Auswahl durch das Gateway.
      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-Anbieter in das Routing einbeziehen (standardmäßig
            deaktiviert).
        allow_fallbacks:
          type: boolean
          nullable: true
          description: Nach einem Fehler auf einen anderen geeigneten Anbieter ausweichen.
        require_parameters:
          type: boolean
          nullable: true
          description: >-
            Vor dem Routing die Unterstützung der angeforderten Parameter durch
            den Anbieter voraussetzen.
        required_execution_region:
          type: string
          nullable: true
          description: >-
            Das Routing auf Anbieter mit der angeforderten Ausführungsregion
            beschränken.
        required_data_region:
          type: string
          nullable: true
          description: >-
            Das Routing auf Anbieter mit der angeforderten Datenregion
            beschränken.
        require_zero_data_retention:
          type: boolean
          nullable: true
          description: >-
            Das Routing auf Anbieter beschränken, die keine Datenspeicherung
            unterstützen.
        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: >-
            Anbieter für diese Anfrage sortieren, zum Beispiel nach Preis,
            Latenz oder Durchsatz.
        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: >-
        Gateway-Debug-Steuerungen. Diese Flags werden niemals an den Anbieter
        weitergeleitet.
      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: Authentifizierung mit Bearer-Token

````

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