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

# 同步人声分离

> 同步上传音频文件并执行人声分离。接口会在处理完成后直接返回分离结果。

## 说明

同步方式进行人声分离。请求需要上传音频文件，并在 HTTP 连接中等待处理完成。处理成功后，接口会直接返回分离后的人声音频 URL。

对于不需要持续保持 HTTP 连接、希望先获取任务 ID 再查询结果的场景，见[异步人声分离 API](/api-reference/endpoint/voice-isolation/async)。

## 音频要求

* 上传字段固定为 `file`
* 支持的音频格式、时长与文件大小限制以服务端校验规则为准
* 当文件不符合模型要求或音频格式非法时，服务端将返回 `400`

<Warning>
  在线 Playground 会先通过文档站代理上传文件，较大的音视频文件可能触发 `413 Request Entity Too Large`。如需测试较大文件，请使用下方 `curl` 示例或 SDK 从本地直连 `https://api.senseaudio.cn`。
</Warning>

## 请求示例

```bash theme={null}
curl --request POST 'https://api.senseaudio.cn/v1/isolation/sync' \
  --header 'Authorization: Bearer <API_KEY>' \
  --form 'model=senseaudio-voice-isolation-1.0-260319' \
  --form 'file=@/path/to/sample.wav'
```


## OpenAPI

````yaml api-reference/endpoint/voice-isolation/voice-isolation.openapi.json POST /v1/isolation/sync
openapi: 3.1.0
info:
  title: SenseAudio - Voice Isolation
  version: 1.0.0
servers:
  - url: https://api.senseaudio.cn
    description: 生产环境
security:
  - bearerAuth: []
paths:
  /v1/isolation/sync:
    post:
      tags:
        - Voice Isolation
      summary: 同步人声分离
      description: 同步上传音频文件并执行人声分离。接口会在处理完成后直接返回分离结果。
      operationId: voiceIsolationSync
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - model
                - file
              properties:
                model:
                  type: string
                  description: 人声分离模型名称
                  enum:
                    - senseaudio-voice-isolation-1.0-260319
                    - senseaudio-voice-isolation-1.5
                  example: senseaudio-voice-isolation-1.0-260319
                file:
                  type: string
                  format: binary
                  description: 待处理的音频文件
      responses:
        '200':
          description: 人声分离成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceIsolationResult'
              example:
                source_file_name: sample.wav
                result_url: https://xxx/voice-isolation/result.mp3
                status: completed
                error_message: ''
        '400':
          description: 请求参数或音频文件不符合要求
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    VoiceIsolationResult:
      type: object
      properties:
        source_file_name:
          type: string
          description: 原始上传文件名
          example: sample.wav
        result_url:
          type: string
          description: 分离结果音频 URL。任务成功时返回；任务处理中或失败时可能为空字符串。
          example: https://xxx/voice-isolation/result.mp3
        status:
          $ref: '#/components/schemas/VoiceIsolationStatus'
        error_message:
          type: string
          description: 错误信息。任务失败时返回失败原因，任务成功或处理中时通常为空字符串。
          example: ''
      required:
        - source_file_name
        - result_url
        - status
        - error_message
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: 错误码
        message:
          type: string
          description: 错误信息
    VoiceIsolationStatus:
      type: string
      description: 任务状态
      enum:
        - pending
        - completed
        - failed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY
      description: 格式：`Bearer <API_KEY>`

````