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

# 文件上传

> 上传文件并获取 file_id。Authorization 直接传 API Key，不需要 Bearer 前缀。

export const VoiceCloneErrorHeading = () => {
  useEffect(() => {
    const section = document.createElement("section");
    section.className = "api-section";
    const heading = document.createElement("h4");
    heading.id = "voice-clone-error-codes";
    heading.className = "api-section-heading-title border-b pb-2.5 border-gray-100 dark:border-gray-800";
    heading.textContent = "错误码";
    section.appendChild(heading);
    const table = document.createElement("table");
    table.className = "w-full text-sm mt-4";
    table.innerHTML = `
      <thead><tr><th>HTTP</th><th>code</th><th>含义</th></tr></thead>
      <tbody>
        <tr><td>400</td><td><code>invalid</code></td><td>本地请求解析或参数校验失败</td></tr>
        <tr><td>401</td><td><code>authentication_error</code></td><td>提供的 API 密钥不正确</td></tr>
      </tbody>`;
    section.appendChild(table);
    const placeHeading = () => {
      const responseHeading = Array.from(document.querySelectorAll(".api-section-heading-title")).find(node => (/^(响应|Response)$/).test(node.textContent.trim()));
      const responseSection = responseHeading?.closest(".api-section");
      if (responseSection && responseSection.nextElementSibling !== section) {
        responseSection.after(section);
      } else if (!responseSection) {
        const main = document.querySelector("main");
        if (main && section.parentElement !== main) {
          main.appendChild(section);
        }
      }
    };
    const observer = new MutationObserver(placeHeading);
    observer.observe(document.body, {
      childList: true,
      subtree: true
    });
    placeHeading();
    return () => {
      observer.disconnect();
      section.remove();
    };
  }, []);
  return null;
};

<VoiceCloneErrorHeading />

## 说明

上传文件并获取 `file_id`。通过 `purpose` 区分用途：

| purpose | 用途 | 音频时长 | 文件大小 | 格式 |
| :- | :- | :- | :- | :- |
| `voice_clone` | 音色克隆参考音频 | 建议 3–30 秒 | ≤ 50 MB | MP3、AAC、WAV |
| `speech_to_text` | 语音识别文件上传 | 1 秒–5 小时 | \< 500 MB | 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"
```

### 语音识别

```bash theme={null}
curl -X POST https://api.senseaudio.cn/v1/files/upload \
  -H "Authorization: <API_KEY>" \
  -F "purpose=speech_to_text" \
  -F "file=@/path/to/audio.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"
  }
}
```

## 下一步

* `purpose=voice_clone`：上传成功后可进行 [SenseAudio 音色克隆](/api-reference/endpoint/voice/clone-senseaudio) 或 [Minimax 兼容音色克隆](/api-reference/endpoint/voice/clone)
* `purpose=speech_to_text`：上传成功后可将返回的 `file_id` 用于 [语音识别转写](/api-reference/endpoint/asr/transcriptions)


## OpenAPI

````yaml api-reference/endpoint/files/upload.openapi.json POST /v1/files/upload
openapi: 3.1.0
info:
  title: SenseAudio - 文件上传
  version: 1.0.0
servers:
  - url: https://api.senseaudio.cn
    description: 生产环境
security: []
paths:
  /v1/files/upload:
    post:
      tags:
        - Files
      summary: 上传音频文件
      description: 上传文件并获取 file_id。Authorization 直接传 API Key，不需要 Bearer 前缀。
      operationId: uploadFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - purpose
              properties:
                file:
                  type: string
                  format: binary
                  description: 上传音频文件
                purpose:
                  type: string
                  description: 文件用途
                  enum:
                    - voice_clone
                    - speech_to_text
                  example: voice_clone
                  x-enumDescriptions:
                    voice_clone: 音色克隆参考音频
                    speech_to_text: 语音识别文件上传
      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
              enum:
                - voice_clone
                - speech_to_text
              example: voice_clone
            created_at:
              type: integer
              example: 1783326931
        base_resp:
          $ref: '#/components/schemas/BaseResp'
    BaseResp:
      type: object
      properties:
        status_code:
          type: integer
          description: 0 表示成功，非 0 表示失败
        status_msg:
          type: string
          description: 状态详情
  securitySchemes:
    authorizationHeader:
      type: apiKey
      in: header
      name: Authorization
      description: 直接传 API Key，例如：sk-xxxx（不需要 Bearer 前缀）

````

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