# Generate Speech

## OpenAPI Specification

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /api/v1/jobs/createTask:
    post:
      summary: Generate Speech
      deprecated: false
      description: >
        Create a Suno Speech generation task. Supports **Simple** and
        **Advanced** modes, switched by `customMode`. The two modes have
        mutually exclusive fields — do not mix them.


        Speech generates spoken audio with tone, rhythm, emotion, and optional
        background music. It is not fixed-voice TTS. The model is always
        `ai-music-api/speech`.


        ### Usage

        #### Simple (`customMode: false`)


        - Required: `customMode`, `prompt` (1–3000 characters)

        - `prompt` is a scene description (Idea prompt); the model writes the
        script

        - Submit only `customMode=false` + `prompt`. Do not send `script` /
        `tone` / `variety` / `vocalGender` / `backgroundMusic`


        #### Advanced (`customMode: true`)


        - Required: `customMode`, `script` (1–5000 characters, the text to be
        spoken)

        - Optional: `tone` (0–1000), `variety` (integer 0–4), `vocalGender`,
        `backgroundMusic`

        - Drop `prompt`. Do not send `prompt` in Advanced


        #### Switching modes


        - Switch to Simple: drop Advanced fields and submit only
        `customMode=false` + `prompt`

        - Switch to Advanced: drop `prompt` and submit `customMode=true` +
        `script`, plus any optional fields


        ### Common 422


        | Case | Message |

        | --- | --- |

        | variety outside 0–4 | `variety must be between 0 and 4` |

        | variety sent in Simple | `variety is only supported when customMode is
        true` |
      operationId: generate-speech
      tags:
        - docs/en/Market/Music Models/Suno/Speech Generation
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                model:
                  type: string
                  description: Model identifier. Always `ai-music-api/speech`.
                  enum:
                    - ai-music-api/speech
                  examples:
                    - ai-music-api/speech
                callBackUrl:
                  type: string
                  title: Callback URL
                  format: uri
                  description: >-
                    The URL to receive generation task completion updates.
                    Optional but recommended for production use.

                    - The system POSTs task status and results to this URL when
                    generation completes

                    - The callback includes generated URLs and task information

                    - Your callback endpoint should accept POST requests with a
                    JSON payload

                    - Alternatively, poll GET /api/v1/jobs/recordInfo?taskId=...
                    (see [Get Task Details](/market/common/get-task-detail)).
                    For Suno audio tasks the tracks are in data.response.data[]
                    (audio_url, stream_audio_url, image_url, id, duration).

                    - To ensure callback security, see [Webhook Verification
                    Guide](/common-api/webhook-verification)
                input:
                  type: object
                  description: >-
                    Input parameters for the generation task. Simple and
                    Advanced fields are mutually exclusive: Simple sends only
                    `customMode=false` and `prompt`; Advanced sends
                    `customMode=true` and `script`, plus optional fields.
                  properties:
                    customMode:
                      type: boolean
                      title: Mode
                      description: >-
                        Mode switch. Required. `false` is Simple, `true` is
                        Advanced.
                      examples:
                        - false
                    prompt:
                      type: string
                      title: Scene prompt
                      description: >-
                        Simple only. A one-line scene description; the model
                        writes the script. Required. After trimming whitespace,
                        1–3000 characters.
                      minLength: 1
                      maxLength: 3000
                      examples:
                        - A short morning news intro about sunny weather
                    script:
                      type: string
                      title: Script
                      description: >-
                        Advanced only. The text to be spoken. Required. After
                        trimming whitespace, 1–5000 characters. Multiline is
                        supported; use `\n` for line breaks in JSON.
                      minLength: 1
                      maxLength: 5000
                      examples:
                        - >-
                          Welcome to today's briefing. The weather is clear and
                          the city is awake.
                    tone:
                      type: string
                      title: Tone
                      description: >-
                        Advanced only, optional. Tone, rhythm, emotion, and
                        setting. You can also describe accent and accompaniment
                        style. After trimming whitespace, 0–1000 characters.
                      maxLength: 1000
                      examples:
                        - Warm, calm female narrator, slightly smiling
                    variety:
                      type: integer
                      title: Variety
                      description: Advanced only, optional. Integer from `0` to `4`.
                      minimum: 0
                      maximum: 4
                      enum:
                        - 0
                        - 1
                        - 2
                        - 3
                        - 4
                      x-apidog-enum:
                        - value: 0
                          name: Exact style
                          description: Exact style
                        - value: 1
                          name: Balanced variety
                          description: Balanced variety
                        - value: 2
                          name: Distinct styles
                          description: Distinct styles
                        - value: 3
                          name: Bold exploration
                          description: Bold exploration
                        - value: 4
                          name: Unreasonably varied
                          description: Unreasonably varied
                      examples:
                        - 1
                    vocalGender:
                      type: string
                      title: Vocal gender
                      description: >-
                        Advanced only, optional. Vocal gender. Case-insensitive.
                        Do not send `female` / `male`.
                      enum:
                        - f
                        - m
                      x-apidog-enum:
                        - value: f
                          name: Female
                          description: Female
                        - value: m
                          name: Male
                          description: Male
                      examples:
                        - f
                    backgroundMusic:
                      type: boolean
                      title: Background music
                      description: >-
                        Advanced only, optional. Whether to add background
                        music.


                        - `true`: On

                        - `false`: Off
                      examples:
                        - true
                  required:
                    - customMode
                  x-apidog-orders:
                    - customMode
                    - prompt
                    - script
                    - tone
                    - variety
                    - vocalGender
                    - backgroundMusic
              required:
                - model
                - input
              x-apidog-orders:
                - model
                - callBackUrl
                - input
              examples:
                - model: ai-music-api/speech
                  callBackUrl: https://your.domain/callback
                  input:
                    customMode: false
                    prompt: A short morning news intro about sunny weather
                - model: ai-music-api/speech
                  callBackUrl: https://your.domain/callback
                  input:
                    customMode: true
                    script: >-
                      Welcome to today's briefing. The weather is clear and the
                      city is awake.
                    tone: Warm, calm female narrator, slightly smiling
                    variety: 1
                    vocalGender: f
                    backgroundMusic: true
            example:
              model: ai-music-api/speech
              callBackUrl: https://your.domain/callback
              input:
                customMode: false
                prompt: A short morning news intro about sunny weather
      responses:
        '200':
          description: >-
            Request succeeded. The task has been created; this does not mean the
            audio is ready.
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      code:
                        type: integer
                        enum:
                          - 200
                          - 401
                          - 402
                          - 404
                          - 409
                          - 422
                          - 429
                          - 451
                          - 455
                          - 500
                        description: >-
                          Request status code. Failed requests still return HTTP
                          200; always use this field: 200 means success, any
                          other value means failure (see msg). Common values:
                          401 invalid or missing API key; 402 insufficient
                          credits; 429 rate limited; 422 validation failed (see
                          Common 422 above); 500 the request could not be
                          processed.
                      msg:
                        type: string
                        description: Error message when code != 200
                        examples:
                          - success
                    x-apidog-orders:
                      - code
                      - msg
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          taskId:
                            type: string
                            description: >-
                              Task ID used to track status. Poll GET
                              /api/v1/jobs/recordInfo?taskId=... (see [Get Task
                              Details](/market/common/get-task-detail)).
                            examples:
                              - xxxxxxxx
                        x-apidog-orders:
                          - taskId
                    x-apidog-orders:
                      - data
          headers: {}
          x-apidog-name: ''
      security:
        - BearerAuth: []
          x-apidog:
            schemeGroups:
              - id: kn8M4YUlc5i0A0179ezwx
                schemeIds:
                  - BearerAuth
            required: true
            use:
              id: kn8M4YUlc5i0A0179ezwx
            scopes:
              kn8M4YUlc5i0A0179ezwx:
                BearerAuth: []
      callbacks:
        audioGenerated:
          '{$request.body#/callBackUrl}':
            post:
              summary: Speech Generation Callback
              description: >-
                The system POSTs task progress and results to the `callBackUrl`
                you provided in up to three stages: `text` (text generated,
                `audio_url` still empty), `first` (first clip complete) and
                `complete` (all clips complete); `text` and `first` may be
                skipped. The payload structure is the same as
                `ai-music-api/generate`. On failure, `code` is not 200, `msg` is
                the failure reason, and `data.data` is empty.


                ### Callback example

                ```json

                {
                  "code": 200,
                  "msg": "All generated successfully.",
                  "data": {
                    "callbackType": "complete",
                    "task_id": "xxxxxxxx",
                    "data": [
                      {
                        "id": "clip-id",
                        "audio_url": "https://example.com/speech.mp3",
                        "stream_audio_url": "https://example.com/speech-stream",
                        "image_url": "https://example.com/cover.jpeg",
                        "title": "",
                        "duration": 12.3
                      }
                    ]
                  }
                }

                ```
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        code:
                          type: integer
                          description: >-
                            Status code. 200 means success; any other value
                            means failure.
                          example: 200
                        msg:
                          type: string
                          description: >-
                            Response message. On failure, this is the failure
                            reason.
                          example: All generated successfully.
                        data:
                          type: object
                          properties:
                            callbackType:
                              type: string
                              description: >-
                                Callback type: `text` (text generated), `first`
                                (first clip complete), `complete` (all clips
                                complete).
                              enum:
                                - text
                                - first
                                - complete
                              example: complete
                            task_id:
                              type: string
                              description: Task ID
                            data:
                              type: array
                              description: List of generated results. Empty on failure.
                              items:
                                type: object
                                properties:
                                  id:
                                    type: string
                                    description: Audio ID
                                  audio_url:
                                    type: string
                                    description: Final downloadable audio URL
                                  stream_audio_url:
                                    type: string
                                    description: Streaming audio URL
                                  image_url:
                                    type: string
                                    description: Cover image URL
                                  title:
                                    type: string
                                    description: Title
                                  duration:
                                    type: number
                                    description: Audio duration in seconds
                    example:
                      code: 200
                      msg: All generated successfully.
                      data:
                        callbackType: complete
                        task_id: xxxxxxxx
                        data:
                          - id: clip-id
                            audio_url: https://example.com/speech.mp3
                            stream_audio_url: https://example.com/speech-stream
                            image_url: https://example.com/cover.jpeg
                            title: ''
                            duration: 12.3
              responses:
                '200':
                  description: Callback received
      x-apidog-folder: docs/en/Market/Music Models/Suno/Speech Generation
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/1184766/apis/api-46863003-run
components:
  schemas: {}
  securitySchemes:
    BearerAuth:
      type: bearer
      scheme: bearer
      bearerFormat: API Key
      description: >-
        All API requests require a Bearer Token. Add the header `Authorization:
        Bearer YOUR_API_KEY` to authenticate requests.
    BearerAuth1:
      type: bearer
      scheme: bearer
      bearerFormat: API Key
      description: >-
        所有 API 请求都需要 Bearer Token。请在请求头中添加 `Authorization: Bearer YOUR_API_KEY`
        进行身份验证。
servers:
  - url: https://api.kie.ai
    description: 正式环境
security:
  - BearerAuth: []
    x-apidog:
      schemeGroups:
        - id: kn8M4YUlc5i0A0179ezwx
          schemeIds:
            - BearerAuth
      required: true
      use:
        id: kn8M4YUlc5i0A0179ezwx
      scopes:
        kn8M4YUlc5i0A0179ezwx:
          BearerAuth: []

```
