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

# SoundClone - 提交音频生成任务

> 使用试听任务得到的 modelId 提交正式音频生成任务。

<Note>
  使用 [试听任务](/zh/api-reference/sound-clone/clone-create) 完成后返回的 `modelId` 提交正式音频生成。任务创建后请通过 [查询声音克隆任务](/zh/api-reference/common/sound-clone-query) 轮询获取 `audioUrl`。

  `modelId` 有效期为 **3 天**；在有效期内首次调用本接口时会自动转正，转正后可永久用于音频生成。

  响应格式：`{ "code": 20000, "msg": "ok", "data": { ... } }`。
</Note>

## 请求参数

| 字段               | 类型      | 必填 | 说明                                                                                      |
| ---------------- | ------- | -- | --------------------------------------------------------------------------------------- |
| `modelId`        | string  | 是  | 声音模型 ID，来自试听任务查询结果中的 `modelId`。                                                         |
| `contentText`    | string  | 是  | 需要生成音频的文本，长度小于 **10000** 字符。可在字间插入 `<#x#>` 控制停顿（`x` 为秒，范围 `0.01–99.99`，最多两位小数）。         |
| `soundVersion`   | string  | 否  | 声音模型版本：`v1` 或 `v2`。                                                                     |
| `language`       | string  | 否  | 语言类型，默认 `auto`。                                                                         |
| `emotion`        | string  | 否  | 情感类型，默认 `neutral`。支持 `happy`、`sad`、`angry`、`fearful`、`disgusted`、`surprised`、`neutral`。 |
| `speed`          | number  | 否  | 语速，范围 `[0.5, 2]`，默认 `1.0`。                                                              |
| `vol`            | number  | 否  | 音量，范围 `(0, 10]`，默认 `1.0`。                                                               |
| `pitch`          | integer | 否  | 语调，范围 `[-12, 12]`，默认 `0`。                                                               |
| `subtitleEnable` | boolean | 否  | 是否生成字幕，默认 `false`。                                                                      |
| `subtitleType`   | string  | 否  | 字幕类型。开启字幕时可传 `word`（字级别）；不传为句级别。                                                        |

### 支持语言（节选）

**v1 / v2 均支持：** `Chinese`（中文）、`Chinese,Yue`（粤语）、`English`、`Japanese`、`Korean`、`French`、`German`、`Spanish` 等 24 种语言。

**仅 v2 支持：** `Bulgarian`、`Danish`、`Hebrew`、`Malay`、`Persian`、`Swedish`、`Tamil`、`auto`（自动检测）等。

## 计费说明

正式音频包含两部分费用：

| 模型配置名                 | 说明                                       |
| --------------------- | ---------------------------------------- |
| `sound-cloning-audio` | 按 `contentText` 字符数计费，单位为每 **1 万字符**     |
| `sound-cloning-voice` | **音色费**：每次提交正式音频任务均收取（按次，与 `modelId` 无关） |

字符数统计规则与试听一致：按 Unicode 字符计数，排除 `<#x#>` 停顿标记。

## 示例请求

```bash theme={null}
curl --request POST \
  --url 'https://www.jimmyai.cn/api/open-api/v1/soundCloning/audios' \
  --header 'Authorization: Bearer sk_xxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "modelId": "model_123456789",
    "contentText": "欢迎使用声音克隆能力，这是一段用于生成正式音频的文本。",
    "language": "Chinese",
    "soundVersion": "v1",
    "emotion": "neutral",
    "speed": 1.0,
    "vol": 1.0,
    "pitch": 0,
    "subtitleEnable": false
  }'
```

## 响应示例

```json theme={null}
{
  "code": 20000,
  "msg": "ok",
  "data": {
    "id": "audio_764fb3e7-8af2-4d2d-89a0-e58f8f3eb9c4",
    "object": "audio",
    "created": 1781777280,
    "model": "soundCloningAudio",
    "status": "queued",
    "error": null
  }
}
```


## OpenAPI

````yaml zh/api-reference/openapi.json POST /api/open-api/v1/soundCloning/audios
openapi: 3.1.0
info:
  title: Jimmy AI OpenAPI
  description: API for Jimmy AI video generation services
  version: 1.0.0
servers:
  - url: https://www.jimmyai.cn
    description: Production server
security:
  - bearerAuth: []
paths:
  /api/open-api/v1/soundCloning/audios:
    post:
      summary: SoundClone - 提交音频生成任务
      description: 使用试听任务得到的 modelId 提交正式音频生成任务。
      operationId: createSoundCloneAudio
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SoundCloneAudioRequest'
            examples:
              production:
                summary: 提交正式音频
                value:
                  modelId: model_123456789
                  contentText: 欢迎使用声音克隆能力，这是一段用于生成正式音频的文本。
                  language: Chinese
                  soundVersion: v1
                  emotion: neutral
                  speed: 1
                  vol: 1
                  pitch: 0
                  subtitleEnable: false
      responses:
        '200':
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SoundCloneApiResponse'
              examples:
                queued:
                  summary: 创建成功
                  value:
                    code: 20000
                    msg: ok
                    data:
                      id: audio_764fb3e7-8af2-4d2d-89a0-e58f8f3eb9c4
                      object: audio
                      created: 1781777280
                      model: soundCloningAudio
                      status: queued
                      error: null
components:
  schemas:
    SoundCloneAudioRequest:
      type: object
      required:
        - modelId
        - contentText
      properties:
        modelId:
          type: string
          description: 试听任务完成后返回的声音模型 ID
        contentText:
          type: string
          description: 生成音频的文本，小于 10000 字符
        soundVersion:
          type: string
          enum:
            - v1
            - v2
        language:
          type: string
          default: auto
        emotion:
          type: string
          enum:
            - happy
            - sad
            - angry
            - fearful
            - disgusted
            - surprised
            - neutral
          default: neutral
        speed:
          type: number
          minimum: 0.5
          maximum: 2
          default: 1
        vol:
          type: number
          exclusiveMinimum: 0
          maximum: 10
          default: 1
        pitch:
          type: integer
          minimum: -12
          maximum: 12
          default: 0
        subtitleEnable:
          type: boolean
          default: false
        subtitleType:
          type: string
          enum:
            - word
          description: 不传为句级别字幕
      example:
        modelId: model_123456789
        contentText: 欢迎使用声音克隆能力，这是一段用于生成正式音频的文本。
        language: Chinese
        soundVersion: v1
        emotion: neutral
        speed: 1
        vol: 1
        pitch: 0
        subtitleEnable: false
    SoundCloneApiResponse:
      type: object
      properties:
        code:
          type: integer
          example: 20000
        msg:
          type: string
          example: ok
        data:
          $ref: '#/components/schemas/SoundCloneTaskData'
    SoundCloneTaskData:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: audio
        created:
          type: integer
          format: int64
        model:
          type: string
          enum:
            - soundCloningClone
            - soundCloningAudio
        status:
          type: string
          enum:
            - queued
            - processing
            - completed
            - failed
        error:
          type:
            - string
            - 'null'
      example:
        id: audio_16b635ba-5889-4fa5-bbcc-bf67a38c353a
        object: audio
        created: 1781777280
        model: soundCloningClone
        status: queued
        error: null
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````