# Seed Audio 1.0 Audio Generation

> Audio Generation

Submit an audio generation request. The request carries a prompt,
optional reference resources, and audio settings; the response is a
binary audio stream.

## Endpoint

`POST https://api.modelverse.cn/v1/audio/speech`

## Request Body

## Responses

- **200** — Binary audio data whose encoding is defined by `audio_config.format`.
- **400** — Invalid request parameters.
- **default** — Error response.

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "ModelVerse Seed Audio 1.0 Speech API",
    "version": "1.0.0",
    "description": "`seed-audio-1.0`\nThe endpoint is compatible with the OpenAI `/v1/audio/speech` path, but the\nresponse body is a binary audio stream, not JSON. The audio format is\ncontrolled by `audio_config.format`, and the response `Content-Type` is\nderived from `audio_config.format`, falling back to\n`response_format` when it is omitted.\n\nThree generation modes are selected automatically by whether `references`\nis present:\n\n- Text-only generation: send `text_prompt` only; audio is generated from the\n  prompt description.\n- Reference-audio generation: send an audio reference in `references`\n  (`speaker` / `audio_data` / `audio_url`) and refer to it with `@音频N`\n  inside `text_prompt`.\n- Reference-image generation: send an image reference in `references`\n  (`image_data` / `image_url`); `text_prompt` then carries only the text to\n  synthesize.\n\nA single request can generate up to 120 seconds of audio. Billing is based\non the model output duration `original_duration` in seconds.\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint shown in the source document."
    }
  ],
  "tags": [
    {
      "name": "Seed Audio 1.0",
      "description": "Volcengine Seed Audio 1.0 audio generation for sound effects, dubbing, and voice cloning."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/audio/speech": {
      "post": {
        "tags": [
          "Seed Audio 1.0"
        ],
        "operationId": "createSeedAudioSpeech",
        "summary": "Seed Audio 1.0 Audio Generation",
        "description": "Submit an audio generation request. The request carries a prompt,\noptional reference resources, and audio settings; the response is a\nbinary audio stream.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SeedAudioSpeechRequest"
              },
              "examples": {
                "textOnly": {
                  "summary": "Text-only generation (sound effect with dialogue)",
                  "value": {
                    "model": "seed-audio-1.0",
                    "text_prompt": "A phone vibrates once, birds keep chirping in the background. The music is led by marimba with a synth lead, electric bass, and percussion, creating a tense and suspenseful mood.",
                    "audio_config": {
                      "format": "mp3",
                      "sample_rate": 48000
                    }
                  }
                },
                "systemSpeaker": {
                  "summary": "Synthesis with a system voice",
                  "value": {
                    "model": "seed-audio-1.0",
                    "text_prompt": "Welcome to ModelVerse Seed Audio generation service.",
                    "references": [
                      {
                        "speaker": "zh_female_vv_uranus_bigtts"
                      }
                    ],
                    "audio_config": {
                      "format": "wav",
                      "sample_rate": 40000,
                      "speech_rate": 0,
                      "loudness_rate": 0,
                      "pitch_rate": 0
                    }
                  }
                },
                "referenceAudioByUrl": {
                  "summary": "Reference-audio generation using @音频N",
                  "value": {
                    "model": "seed-audio-1.0",
                    "text_prompt": "@音频1 Say in a low, husky voice: since you already know, there is nothing left for me to hide.",
                    "references": [
                      {
                        "audio_url": "https://example.com/speaker.wav"
                      }
                    ],
                    "audio_config": {
                      "format": "mp3",
                      "sample_rate": 44100
                    }
                  }
                },
                "referenceImage": {
                  "summary": "Reference-image generation",
                  "value": {
                    "model": "seed-audio-1.0",
                    "text_prompt": "A small bird chirps brightly in a forest at dawn.",
                    "references": [
                      {
                        "image_url": "https://example.com/bird.png"
                      }
                    ],
                    "audio_config": {
                      "format": "wav",
                      "sample_rate": 40000
                    }
                  }
                },
                "withSubtitleAndWatermark": {
                  "summary": "Subtitle timestamps and AIGC watermark enabled",
                  "value": {
                    "model": "seed-audio-1.0",
                    "text_prompt": "This is a sample clip that requires word-level timestamps.",
                    "references": [
                      {
                        "speaker": "zh_male_m191_uranus_bigtts"
                      }
                    ],
                    "audio_config": {
                      "format": "mp3",
                      "sample_rate": 44100,
                      "enable_subtitle": true
                    },
                    "watermark": {
                      "aigc_watermark": true,
                      "aigc_metadata": {
                        "enable": true,
                        "content_producer": "modelverse",
                        "produce_id": "seed-audio-1.0",
                        "content_propagator": "modelverse",
                        "propagate_id": "seed-audio-1.0"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Binary audio data whose encoding is defined by `audio_config.format`.",
            "content": {
              "audio/wav": {
                "schema": {
                  "$ref": "#/components/schemas/SeedAudioBinary"
                },
                "examples": {
                  "wavAudio": {
                    "summary": "wav audio (default)",
                    "value": "<binary wav audio stream>"
                  }
                }
              },
              "audio/mpeg": {
                "schema": {
                  "$ref": "#/components/schemas/SeedAudioBinary"
                },
                "examples": {
                  "mp3Audio": {
                    "summary": "mp3 audio",
                    "value": "<binary mp3 audio stream>"
                  }
                }
              },
              "audio/ogg": {
                "schema": {
                  "$ref": "#/components/schemas/SeedAudioBinary"
                },
                "examples": {
                  "oggOpusAudio": {
                    "summary": "ogg_opus audio",
                    "value": "<binary ogg_opus audio stream>"
                  }
                }
              },
              "application/octet-stream": {
                "schema": {
                  "$ref": "#/components/schemas/SeedAudioBinary"
                },
                "examples": {
                  "pcmAudio": {
                    "summary": "Raw pcm audio",
                    "value": "<binary pcm audio stream>"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SeedAudioErrorResponse"
                },
                "examples": {
                  "invalidRequest": {
                    "$ref": "#/components/examples/SeedAudioError"
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SeedAudioErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/SeedAudioError"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "ModelVerse API key sent as `Authorization: Bearer <MODELVERSE_API_KEY>`."
      }
    },
    "schemas": {
      "SeedAudioSpeechRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "text_prompt"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "seed-audio-1.0",
            "description": "Audio generation model name. This schema is pinned to `seed-audio-1.0`."
          },
          "text_prompt": {
            "type": "string",
            "maxLength": 3000,
            "description": "Prompt or text to synthesize, up to 3000 characters. For text-only\ngeneration this is the free-form description; for reference-audio\ngeneration use `@音频1`, `@音频2` in upload order to refer to\nentries in `references`; for reference-image generation pass only\nthe text to synthesize.\n\nFor OpenAI `/v1/audio/speech` compatibility, `input` is also\naccepted as an alias. When both are sent, `text_prompt` wins.\n"
          },
          "input": {
            "type": "string",
            "maxLength": 3000,
            "description": "OpenAI-compatible alias for `text_prompt`. It is used only when\n`text_prompt` is empty.\n"
          },
          "response_format": {
            "type": "string",
            "enum": [
              "wav",
              "mp3",
              "pcm",
              "ogg_opus"
            ],
            "default": "wav",
            "description": "Fallback for the output format. The response `Content-Type` is\nderived from `audio_config.format` first and only uses this field\nwhen `audio_config.format` is omitted: `wav` → `audio/wav`,\n`mp3` → `audio/mpeg`, `ogg_opus` → `audio/ogg`, and `pcm` →\n`application/octet-stream`. The actual audio encoding is always\ndefined by `audio_config.format`; keep the two values consistent.\n"
          },
          "references": {
            "type": "array",
            "maxItems": 4,
            "description": "Reference resources. The generation mode is derived from what is\npassed. When omitted, the request is text-only generation.\n\n- Audio references: up to 3 items, each at most 30 seconds and\n  10 MB, supporting `wav` / `mp3` / `pcm` / `ogg_opus`. Upload order\n  must match the `@音频N` indices used in `text_prompt`.\n- Image references: up to 1 item, at most 10 MB, supporting\n  `jpeg` / `png` / `webp`.\n- Image references cannot be mixed with audio references:\n  `image_data` / `image_url` must not be combined with `speaker` /\n  `audio_data` / `audio_url`.\n",
            "items": {
              "$ref": "#/components/schemas/SeedAudioReference"
            }
          },
          "audio_config": {
            "$ref": "#/components/schemas/SeedAudioConfig"
          },
          "watermark": {
            "$ref": "#/components/schemas/SeedAudioWatermark"
          }
        }
      },
      "SeedAudioReference": {
        "type": "object",
        "additionalProperties": false,
        "description": "A single reference resource. `speaker`, `audio_data`, and `audio_url` are mutually exclusive; `image_data` and `image_url` are mutually exclusive.",
        "properties": {
          "speaker": {
            "type": "string",
            "description": "Voice ID. Both \"Doubao Speech Synthesis Model 2.0\" voices and voice\ncloning voices are supported. The full voice list is published at\nhttps://docs.volcengine.com/docs/doubao-voice/tone-list-3\n\nMutually exclusive with `audio_data` and `audio_url`.\n",
            "examples": [
              "zh_female_vv_uranus_bigtts",
              "zh_female_xiaohe_uranus_bigtts",
              "zh_male_m191_uranus_bigtts",
              "zh_male_taocheng_uranus_bigtts",
              "en_female_dacey_uranus_bigtts",
              "en_male_tim_uranus_bigtts"
            ]
          },
          "audio_data": {
            "type": "string",
            "description": "Base64-encoded reference audio. Mutually exclusive with `speaker` and `audio_url`."
          },
          "audio_url": {
            "type": "string",
            "format": "uri",
            "description": "Remote URL of the reference audio. Mutually exclusive with `speaker` and `audio_data`."
          },
          "image_data": {
            "type": "string",
            "description": "Base64-encoded reference image. Mutually exclusive with `image_url` and cannot be mixed with audio references."
          },
          "image_url": {
            "type": "string",
            "format": "uri",
            "description": "Remote URL of the reference image. Mutually exclusive with `image_data` and cannot be mixed with audio references."
          }
        }
      },
      "SeedAudioConfig": {
        "type": "object",
        "additionalProperties": false,
        "description": "Output audio configuration.",
        "properties": {
          "format": {
            "type": "string",
            "enum": [
              "wav",
              "mp3",
              "pcm",
              "ogg_opus"
            ],
            "default": "wav",
            "description": "Output audio format. Defaults to `wav`. This field also determines\nthe response `Content-Type` (see the mapping table on\n`response_format`).\n"
          },
          "sample_rate": {
            "type": "integer",
            "default": 40000,
            "description": "Output sample rate in Hz. Supported values depend on the format:\n\n- `wav` / `pcm`: default 40000; allowed 8000, 16000, 24000, 32000, 40000, 44100, 48000\n- `mp3`: default 44100; allowed 8000, 16000, 24000, 32000, 44100, 48000\n- `ogg_opus`: only 48000\n",
            "examples": [
              40000,
              44100,
              48000
            ]
          },
          "speech_rate": {
            "type": "integer",
            "minimum": -50,
            "maximum": 100,
            "default": 0,
            "description": "Speech rate, default 0. Higher values speak faster; -50 means 0.5x and 100 means 2.0x."
          },
          "loudness_rate": {
            "type": "integer",
            "minimum": -50,
            "maximum": 100,
            "default": 0,
            "description": "Volume, default 0. Higher values are louder; -50 means 0.5x and 100 means 2.0x."
          },
          "pitch_rate": {
            "type": "integer",
            "minimum": -12,
            "maximum": 12,
            "default": 0,
            "description": "Pitch, default 0. Higher values raise the pitch; the allowed range is [-12, 12]."
          },
          "enable_subtitle": {
            "type": "boolean",
            "default": false,
            "description": "Whether to enable subtitle generation, default `false`. When\nenabled the upstream service returns word-level timestamps, but\nthis endpoint returns a binary audio stream, so subtitle data is\nnot included in the response body.\n"
          }
        }
      },
      "SeedAudioWatermark": {
        "type": "object",
        "additionalProperties": false,
        "description": "Watermark configuration. No watermark is added when omitted.",
        "properties": {
          "aigc_watermark": {
            "type": "boolean",
            "default": false,
            "description": "Explicit watermark switch, default `false`. When enabled, an audio rhythm marker is appended at the end of the synthesized audio."
          },
          "aigc_metadata": {
            "$ref": "#/components/schemas/SeedAudioWatermarkMetadata"
          }
        }
      },
      "SeedAudioWatermarkMetadata": {
        "type": "object",
        "additionalProperties": false,
        "description": "Implicit watermark. When enabled, metadata is embedded into the synthesized audio header; disabled by default.",
        "properties": {
          "enable": {
            "type": "boolean",
            "default": false,
            "description": "Whether to enable the implicit watermark, default `false`."
          },
          "content_producer": {
            "type": "string",
            "description": "Name or code of the synthesis service provider."
          },
          "produce_id": {
            "type": "string",
            "description": "Content production ID."
          },
          "content_propagator": {
            "type": "string",
            "description": "Name or code of the content propagation service provider."
          },
          "propagate_id": {
            "type": "string",
            "description": "Content propagation ID."
          }
        }
      },
      "SeedAudioBinary": {
        "type": "string",
        "format": "binary",
        "description": "Generated binary audio data whose encoding is defined by `audio_config.format`."
      },
      "SeedAudioErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/SeedAudioError"
          }
        }
      },
      "SeedAudioError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "message",
          "type",
          "code",
          "param"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Error description."
          },
          "type": {
            "type": "string",
            "description": "Error type.",
            "examples": [
              "invalid_request_error"
            ]
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code.",
            "examples": [
              "error_code"
            ]
          },
          "param": {
            "type": "string",
            "description": "Request ID used for feedback or troubleshooting."
          }
        }
      }
    },
    "examples": {
      "SeedAudioError": {
        "summary": "Standard JSON error response",
        "value": {
          "error": {
            "message": "错误描述信息",
            "type": "invalid_request_error",
            "code": "error_code",
            "param": "<请求 ID，用于反馈或排查错误原因>"
          }
        }
      }
    }
  }
}
```