> ## Documentation Index
> Fetch the complete documentation index at: https://docs.senseaudio.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 音频生成

> 通过文本、参考音色和参考音频生成完整音频

<RequestExample dropdown>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.senseaudio.cn/v1/audio/generate \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "senseaudio-a1",
      "prompt": "@male_0029_a 别太在意他人评价，做好自己的事才是最实在的。",
      "references": []
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.senseaudio.cn/v1/audio/generate",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "senseaudio-a1",
          "prompt": "@male_0029_a 别太在意他人评价，做好自己的事才是最实在的。",
          "references": [],
      },
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.senseaudio.cn/v1/audio/generate", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "senseaudio-a1",
      prompt: "@male_0029_a 别太在意他人评价，做好自己的事才是最实在的。",
      references: [],
    }),
  });
  console.log(await response.json());
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.senseaudio.cn/v1/audio/generate");
  curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          "Authorization: Bearer YOUR_API_KEY",
          "Content-Type: application/json",
      ],
      CURLOPT_POSTFIELDS => json_encode([
          "model" => "senseaudio-a1",
          "prompt" => "@male_0029_a 别太在意他人评价，做好自己的事才是最实在的。",
          "references" => [],
      ], JSON_UNESCAPED_UNICODE),
      CURLOPT_RETURNTRANSFER => true,
  ]);
  $response = curl_exec($ch);
  curl_close($ch);
  echo $response;
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "fmt"
      "io"
      "net/http"
  )

  func main() {
      body := []byte(`{"model":"senseaudio-a1","prompt":"@male_0029_a 别太在意他人评价，做好自己的事才是最实在的。","references":[]}`)
      req, _ := http.NewRequest("POST", "https://api.senseaudio.cn/v1/audio/generate", bytes.NewReader(body))
      req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
      req.Header.Set("Content-Type", "application/json")
      resp, _ := http.DefaultClient.Do(req)
      defer resp.Body.Close()
      result, _ := io.ReadAll(resp.Body)
      fmt.Println(string(result))
  }
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class AudioGenerate {
    public static void main(String[] args) throws Exception {
      var request = HttpRequest.newBuilder()
          .uri(URI.create("https://api.senseaudio.cn/v1/audio/generate"))
          .header("Authorization", "Bearer YOUR_API_KEY")
          .header("Content-Type", "application/json")
          .POST(HttpRequest.BodyPublishers.ofString(
              "{\"model\":\"senseaudio-a1\",\"prompt\":\"@male_0029_a 别太在意他人评价，做好自己的事才是最实在的。\",\"references\":[]}"))
          .build();
      var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
      System.out.println(response.body());
    }
  }
  ```

  ```ruby Ruby theme={null}
  require "net/http"
  require "json"

  uri = URI("https://api.senseaudio.cn/v1/audio/generate")
  request = Net::HTTP::Post.new(uri)
  request["Authorization"] = "Bearer YOUR_API_KEY"
  request["Content-Type"] = "application/json"
  request.body = {
    model: "senseaudio-a1",
    prompt: "@male_0029_a 别太在意他人评价，做好自己的事才是最实在的。",
    references: []
  }.to_json
  puts Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request).body }
  ```
</RequestExample>

## 说明

通过提示词生成完整音频。你可以在提示词中编排角色对白、背景音乐和环境音效，并使用平台音色、个人音色或参考音频控制声音表现。

* **接口地址**：`POST https://api.senseaudio.cn/v1/audio/generate`
* **鉴权方式**：Bearer Token，详见 [快速接入](/guides/account/quick-access)
* **模型**：`senseaudio-a1`
* **最大生成时长**：120 秒（以 `model_duration` 计）
* **计费**：按 `model_duration` 计费，每秒 85 积分。详见 [计费规则](/guides/account/billing)

<Note>
  生成音频的最终时长为 `duration`。当设置 `speech_rate` 时，最终时长可能与模型实际生成时长 `model_duration` 不同；计费始终以 `model_duration` 为准。
</Note>

## 请求参数

### 顶层参数

| 参数名 | 类型 | 必填 | 说明 |
| - | - | :-: | - |
| `model` | string | 是 | 固定为 `senseaudio-a1`。 |
| `prompt` | string | 是 | 音频生成提示词，不能为空，最多 3000 个 Unicode 码点。可描述角色、台词、情绪、背景音乐、环境音效和声音顺序。 |
| `audio_config` | object | 否 | 输出音频配置。所有子字段均为可选。 |
| `references` | array | 否 | 参考音频列表，最多包含 3 条参考音频。 |

### `audio_config` 参数

| 参数名 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `enable_subtitle` | boolean | `true` | 是否返回字幕信息。未传入时默认返回。 |
| `format` | string | — | 输出格式：`wav`、`mp3`。 |
| `loudness_rate` | integer | `0` | 音量调整，范围 `[-50, 100]`。`-50` 表示音量减半，`100` 表示音量增加一倍。 |
| `pitch_rate` | integer | `0` | 音调调整，范围 `[-12, 12]`。 |
| `sample_rate` | integer | — | 采样率（Hz）：`8000`、`16000`、`24000`、`32000`、`40000`、`44100`、`48000`。 |
| `speech_rate` | integer | `0` | 语速调整，范围 `[-50, 100]`。`-50` 表示速度减半，`100` 表示速度增加一倍。 |

### `references` 元素

每个元素提供一条参考音频。

| 参数名 | 类型 | 说明 |
| - | - | - |
| `audio_url` | string | 参考音频地址。最多 3 条，单条时长不得超过 30 秒。 |

`audio_url` 支持以下格式：

* `http` / `https` URL，例如 `https://example.com/test.wav`
* Data URI，例如 `data:audio/x-wav;base64,...`

## 使用音色和参考音频

你可以在 `prompt` 中引用平台音色、个人音色和参考音频：

* 使用 `@<音色标签>` 引用平台内置音色或你已生成/克隆的音色，例如 `@male_0029_a`。
* 使用 `@音频<序号>` 引用 `references` 内的参考音频，序号从 1 开始，例如 `@音频1`。
* 如不希望 `@...` 被识别为音色或参考音频，请使用反斜杠转义，例如 `\@male_0029_a`。
* 音色标签数量与参考音频数量之和不得超过 3。

### 使用参考音频的请求示例

```json theme={null}
{
  "model": "senseaudio-a1",
  "prompt": "@音频1 别太在意他人评价，做好自己的事才是最实在的。",
  "references": [
    {
      "audio_url": "https://example.com/reference.wav"
    }
  ]
}
```

## 响应参数

| 参数名 | 类型 | 说明 |
| - | - | - |
| `audio_url` | string | 生成音频的访问地址。 |
| `duration` | number | 最终音频总时长，单位为秒。 |
| `model_duration` | number | 模型实际生成时长，单位为秒，也是计费时长。 |
| `subtitle` | object | 字幕信息。仅当 `audio_config.enable_subtitle` 为 `true` 或未设置时返回。 |
| `subtitle.text` | string | 全部字幕文本。 |
| `subtitle.sentences` | array | 按句切分的字幕列表。 |
| `subtitle.sentences[].text` | string | 当前句文本。 |
| `subtitle.sentences[].start_time` | integer | 当前句开始时间戳，单位为毫秒。 |
| `subtitle.sentences[].end_time` | integer | 当前句结束时间戳，单位为毫秒。 |
| `subtitle.sentences[].words` | array | 按词切分的时间戳信息。 |

## 响应示例

```json theme={null}
{
  "audio_url": "https://example.com/generated-audio.wav",
  "duration": 5.215,
  "model_duration": 5.215,
  "subtitle": {
    "text": "别太在意他人评价，做好自己的事才是最实在的。",
    "sentences": [
      {
        "start_time": 0,
        "end_time": 5160,
        "text": "别太在意他人评价，做好自己的事才是最实在的。",
        "words": [
          {
            "start_time": 0,
            "end_time": 280,
            "text": "别"
          }
        ]
      }
    ]
  }
}
```

## 错误详情

| status\_msg | 业务含义 |
| - | - |
| `model not found` | 未找到模型 |
| `audio too long` | 参考音频时长超限 |
| `generated audio too long` | 生成的音频过长（120s） |
| `prompt text is longer than 3000 codepoints` | 音频生成提示词（prompt）超过 3000 个 Unicode 码点 |
| `reference download failed` | 参考音频下载失败 |
| `unsupported output format` | 生成音频格式不支持 |
| `unsupported output sample rate` | 生成音频采样率不支持 |
| `unsupported output speech rate` | 生成音频速度不支持 |
| `unsupported loudness rate` | 生成音频音量不支持 |
| `unsupported pitch rate` | 生成音频音调不支持 |
| `empty prompt` | 音频生成提示词为空 |
| `invalid URL` / `invalid reference url` | 参考音频格式错误 |
| `invalid reference` | 参考音频 Data URI 格式错误 |
| `more than 3 audio references and voice ids provided` | 参考音频和引用的音色超过 3 个 |
| `voice XXX cannot be used in this session` | 不能使用指定的音色 |
| `voice XXX not found` | 找不到指定的音色 |
| `incorrect API key provided` | 无效或错误的 API Key |
| `your account is disabled` | 账户已被禁用 |
| `invalid authorization` | 认证错误 |
| `you exceeded your current quota` | 超出当前配额 |
| `this api key is not allowed to access the requested model type` | API Key 不能调用此模型 |
| `internal error, please try later again` | 服务内部错误 |


## OpenAPI

````yaml POST /v1/audio/generate
openapi: 3.1.0
info:
  title: SenseAudio Open Platform API
  description: >-
    SenseAudio 开放平台
    API，覆盖语音合成、音频生成、语音识别、音色能力、音乐生成、图片生成、视频生成、智能体与大语言模型等能力。未显式说明的字段为依据素材文档推断。
  version: 1.0.0
servers:
  - url: https://api.senseaudio.cn
    description: 生产环境
security:
  - bearerAuth: []
paths:
  /v1/audio/generate:
    post:
      tags:
        - Audio
      summary: 音频生成
      description: 基于提示词生成完整音频，支持引用平台音色、个人音色和参考音频。按 model_duration 计费，每秒 85 积分。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - prompt
              properties:
                model:
                  type: string
                  const: senseaudio-a1
                  default: senseaudio-a1
                  description: 音频生成模型。
                prompt:
                  type: string
                  minLength: 1
                  maxLength: 3000
                  description: >-
                    音频生成提示词，不能为空，最多 3000 个 Unicode 码点。可使用 @<音色标签> 引用音色，或使用
                    @音频<序号> 引用参考音频。
                audio_config:
                  type: object
                  description: 输出音频配置。所有子字段均为可选。
                  properties:
                    enable_subtitle:
                      type: boolean
                      default: true
                      description: 是否返回字幕信息。
                    format:
                      type: string
                      enum:
                        - wav
                        - mp3
                      description: 输出音频格式。
                    loudness_rate:
                      type: integer
                      default: 0
                      minimum: -50
                      maximum: 100
                      description: 音量调整比例。
                    pitch_rate:
                      type: integer
                      default: 0
                      minimum: -12
                      maximum: 12
                      description: 音调调整。
                    sample_rate:
                      type: integer
                      enum:
                        - 8000
                        - 16000
                        - 24000
                        - 32000
                        - 40000
                        - 44100
                        - 48000
                      description: 采样率，单位 Hz。
                    speech_rate:
                      type: integer
                      default: 0
                      minimum: -50
                      maximum: 100
                      description: 语速调整比例。
                references:
                  type: array
                  maxItems: 3
                  description: 参考音频列表，单条参考音频不超过 30 秒。
                  items:
                    type: object
                    properties:
                      audio_url:
                        type: string
                        description: 参考音频地址，支持 http/https URL 或 Data URI。
            example:
              model: senseaudio-a1
              prompt: '@male_0029_a 别太在意他人评价，做好自己的事才是最实在的。'
              references: []
      responses:
        '200':
          description: 生成成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  audio_url:
                    type: string
                    format: uri
                    description: 生成音频 URL。
                  duration:
                    type: number
                    description: 最终音频时长，单位秒。
                  model_duration:
                    type: number
                    description: 模型实际生成时长，单位秒，也是计费时长。
                  subtitle:
                    type: object
                    description: 字幕信息。
              example:
                audio_url: https://example.com/generated-audio.wav
                duration: 5.215
                model_duration: 5.215
                subtitle:
                  text: 别太在意他人评价，做好自己的事才是最实在的。
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY
      description: 格式：`Bearer <API_KEY>`

````

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