> ## 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.

# 音色克隆上传文件

> 上传音色克隆参考音频。Authorization 直接传 API Key，不需要 Bearer 前缀；purpose 固定传 voice_clone。

## 说明

上传音频文件并获取 `file_id`，用于后续音色克隆接口引用。音色克隆场景下，`purpose` 固定传 `voice_clone`。

* **音频要求**：建议上传 **3-30 秒** 的清晰人声音频，文件大小 **50MB 以内**，支持 **MP3、AAC、WAV** 格式。
* **请求格式**：使用 `multipart/form-data`，文件字段必须以二进制文件形式上传。
* **结果使用**：后续克隆接口中的 `file_id` 使用返回值里的 `file.file_id`。

## 调用示例

```bash theme={null}
curl -X POST https://api.senseaudio.cn/v1/files/upload \
  -H "Authorization: <API_KEY>" \
  -F "purpose=voice_clone" \
  -F "file=@/path/to/voice.wav"
```

<Note>
  上传文件接口的 `Authorization` 直接传 API Key，不需要 `Bearer` 前缀。`-F "file=@/path/to/voice.wav"` 中的 `@` 不能省略；省略后会上传字符串路径，而不是文件内容。
</Note>

## 成功返回示例

```json theme={null}
{
  "file": {
    "file_id": "file-E4avzR574Mm42YoCytmiND",
    "filename": "温柔御姐_1782460863330.wav",
    "bytes": 228778,
    "purpose": "voice_clone",
    "created_at": 1783326931
  },
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}
```

## 下一步

上传成功后，您可以选择以下任一方式生成克隆音色：

* [SenseAudio 音色克隆](/api-reference/endpoint/voice/clone-senseaudio)
* [Minimax 兼容音色克隆](/api-reference/endpoint/voice/clone)


## OpenAPI

````yaml POST /v1/files/upload
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/files/upload:
    post:
      tags:
        - Files
      summary: 上传音频文件
      description: >-
        上传音色克隆参考音频。Authorization 直接传 API Key，不需要 Bearer 前缀；purpose 固定传
        voice_clone。
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - purpose
              properties:
                file:
                  type: string
                  format: binary
                  description: 参考音频文件。建议 3-30 秒，文件大小 50MB 以内，支持 MP3、AAC、WAV 格式。
                purpose:
                  type: string
                  const: voice_clone
                  default: voice_clone
                  example: voice_clone
                  description: 文件用途。音色克隆场景固定传 voice_clone
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileUploadResponse'
              example:
                file:
                  file_id: file-E4avzR574Mm42YoCytmiND
                  filename: 温柔御姐_1782460863330.wav
                  bytes: 228778
                  purpose: voice_clone
                  created_at: 1783326931
                base_resp:
                  status_code: 0
                  status_msg: success
      security:
        - authorizationHeader: []
components:
  schemas:
    FileUploadResponse:
      type: object
      properties:
        file:
          type: object
          properties:
            file_id:
              type: string
              example: file-E4avzR574Mm42YoCytmiND
            filename:
              type: string
              example: 温柔御姐_1782460863330.wav
            bytes:
              type: integer
              example: 228778
            purpose:
              type: string
              const: voice_clone
              example: voice_clone
            created_at:
              type: integer
              example: 1783326931
        base_resp:
          $ref: '#/components/schemas/BaseResp'
    BaseResp:
      type: object
      description: 通用状态结构
      properties:
        status_code:
          type: integer
          description: 0 表示成功，非 0 表示失败
        status_msg:
          type: string
          description: 状态详情
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY
      description: 格式：`Bearer <API_KEY>`
    authorizationHeader:
      type: apiKey
      in: header
      name: Authorization
      description: 直接传 API Key，例如：sk-xxxx

````