> ## 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 |  是  | 音频生成提示词。可描述角色、台词、情绪、背景音乐、环境音效和声音顺序。 |
| `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": "file-id:file-xxxxxxxx"
    }
  ]
}
```

## 响应参数

| 参数名                               | 类型      | 说明                                                       |
| --------------------------------- | ------- | -------------------------------------------------------- |
| `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": "别"
          }
        ]
      }
    ]
  }
}
```


## 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
                  description: 音频生成提示词。可使用 @<音色标签> 引用音色，或使用 @音频<序号> 引用参考音频。
                audio_config:
                  type: object
                  description: 输出音频配置。所有子字段均为可选。
                  properties:
                    enable_subtitle:
                      type: boolean
                      default: true
                      description: 是否返回字幕信息。
                    format:
                      type: string
                      enum:
                        - wav
                        - mp3
                        - ogg
                      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: 参考音频 URL，支持 http/https、Data URI 或 file-id:<file_id>。
            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>`

````