接口说明

语音合成

shell

POST   https://api.scnet.cn/api/llm/v1/audios/generations
GET    https://api.scnet.cn/api/llm/v1/tasks/{task_id}
POST   https://api.scnet.cn/api/llm/v1/tasks/{task_id}/cancel

1.功能介绍

语音合成接口（Qwen3-TTS-Instruct-Flash）用于将文本合成为语音。接口支持三种交付形态：

非流式同步：请求返回时直接携带合成音频的访问地址。
非流式异步：请求头携带 X-MultiModal-Async: true，提交后返回任务 ID，再通过查询任务状态接口获取合成结果。
流式（SSE）：请求体中设置 stream_format 为 sse，服务端以 Server-Sent Events 形式分帧返回 base64 编码的音频增量，适用于边合成边播放的场景。

2.提交音频任务

shell

POST https://api.scnet.cn/api/llm/v1/audios/generations

2.1 请求参数

名称	类型	必填	示例值	描述
Content-Type	string	是	application/json	\
Authorization	string	是	Bearer <API Key>	\
X-MultiModal-Async	string	否	true	是否以异步任务形态交付。取值 `true` 时提交后返回任务 ID，需轮询任务状态接口获取结果；不传或非 `true` 时默认为 false，同步返回。

Body 参数

名称	类型	必填	默认值	描述
model	string	是	\	调用模型的名称。例如：Qwen3-TTS-Instruct-Flash。
input	object	是	\	输入给模型用于合成语音的信息。
stream_format	string	否	\	流式交付格式。取值 `sse` 时以 Server-Sent Events 流式返回；不传时为非流式返回。

input 参数说明

名称	类型	必填	描述
text	string	是	待合成的文本内容。
voice	string	是	音色标识。
language_type	string	否	语言类型。
instructions	string	否	合成指令，用来控制语气、情感、语速等合成风格。
optimize_instructions	boolean	否	是否对合成指令进行优化。

2.2 响应参数

名称	类型	必填	描述
request_id	string	是	请求唯一标识。可用于请求明细溯源和问题排查。
output	object	是	任务输出信息。
output.task_id	string	是	本次合成任务 ID。
output.task_status	string	是	任务状态。同步返回成功时为 succeeded；异步提交后为 pending。
output.results	array	否	合成音频的访问地址列表。同步返回成功时携带。
output.submit_time	string	否	任务提交时间。
output.end_time	string	否	任务结束时间。
output.error_code	string	否	错误码。任务失败时返回。
output.error_message	string	否	错误信息。任务失败时返回。
usage	object	否	本次请求的用量信息。同步返回时携带。
usage.audio_count	integer	否	合成音频数量。
usage.audio_duration	integer	否	合成音频总时长，单位为秒。
usage.input_chars_num	integer	否	输入字符数。千问3-TTS-Flash 系列按输入字符数计量。
usage.token_usage	object	否	token 用量信息，包含 prompt_tokens、completion_tokens、total_tokens。

2.3 请求示例

cURL请求示例

shell

curl -X POST 'https://api.scnet.cn/api/llm/v1/audios/generations' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <API Key>' \
--data-raw '{
  "model": "Qwen3-TTS-Instruct-Flash",
  "input": {
    "text": "今天天气怎么样？请帮我介绍北京的景点。",
    "voice": "Cherry"
  }
}'

如需以异步任务形态交付，在请求头中添加 X-MultiModal-Async: true：

shell

curl -X POST 'https://api.scnet.cn/api/llm/v1/audios/generations' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <API Key>' \
-H 'X-MultiModal-Async: true' \
--data-raw '{
  "model": "Qwen3-TTS-Instruct-Flash",
  "input": {
    "text": "今天天气怎么样？请帮我介绍北京的景点。",
    "voice": "Cherry"
  }
}'

Python请求示例

python

import requests

url = "https://api.scnet.cn/api/llm/v1/audios/generations"

payload = {
    "model": "Qwen3-TTS-Instruct-Flash",
    "input": {
        "text": "今天天气怎么样？请帮我介绍北京的景点。",
        "voice": "Cherry"
    }
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>"
    # 异步交付时追加： "X-MultiModal-Async": "true"
}

response = requests.post(url, headers=headers, json=payload)
print(response.text)

2.4 响应示例

同步出参

json

{
  "request_id": "1bac5b12361db6a2",
  "output": {
    "task_id": "2069634350003822593",
    "task_status": "succeeded",
    "submit_time": "2026-06-24 12:10:55",
    "end_time": "2026-06-24 12:10:59",
    "results": [
      "https://example.com/audio.wav"
    ],
    "error_code": null,
    "error_message": null
  },
  "usage": {
    "audio_count": 1,
    "audio_duration": 0,
    "input_chars_num": 36,
    "token_usage": {
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "total_tokens": 0
    }
  }
}

异步出参（请求头携带 X-MultiModal-Async: true）

json

{
  "request_id": "93181007-6691-9bf8-810d-c04e37959265",
  "output": {
    "task_id": "e483afa4-9ee0-427e-87e4-e22f90e19f61",
    "task_status": "pending"
  }
}

3.查询任务状态

shell

GET https://api.scnet.cn/api/llm/v1/tasks/{task_id}

异步提交后，使用返回的任务 ID 查询任务状态；任务成功后从 output.results 获取合成音频地址。

3.1 请求参数

名称	类型	必填	示例值
Content-Type	string	是	application/json
Authorization	string	是	Bearer <API Key>

Path 参数

名称	类型	必填	描述
task_id	string	是	需要查询的音频合成任务 ID。

3.2 响应参数

名称	类型	必填	描述
request_id	string	是	请求唯一标识。可用于请求明细溯源和问题排查。
output	object	是	任务输出信息。
output.task_id	string	是	音频合成任务 ID。
output.task_status	string	是	任务状态。常见值包括 pending、running、succeeded、failed、cancelled。
output.submit_time	string	否	任务提交时间。
output.end_time	string	否	任务结束时间。
output.results	array	否	合成音频的访问地址列表。任务成功后返回。
output.error_code	string	否	错误码。任务失败时返回。
output.error_message	string	否	错误信息。任务失败时返回。
usage	object	否	本次请求的用量信息。
usage.audio_count	integer	否	合成音频数量。
usage.input_chars_num	integer	否	输入字符数。
usage.token_usage	object	否	token 用量信息，包含 prompt_tokens、completion_tokens、total_tokens。

3.3 请求示例

cURL请求示例

shell

curl -X GET 'https://api.scnet.cn/api/llm/v1/tasks/<task_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <API Key>'

Python请求示例

python

import requests

task_id = "<task_id>"
url = f"https://api.scnet.cn/api/llm/v1/tasks/{task_id}"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>"
}

response = requests.get(url, headers=headers)
print(response.text)

3.4 响应示例

json

{
  "request_id": "request_id_69f779fb585a",
  "output": {
    "task_id": "2069634350003822593",
    "task_status": "succeeded",
    "submit_time": "2026-06-24 12:10:55",
    "end_time": "2026-06-24 12:10:59",
    "results": [
      "https://example.com/audio.wav"
    ],
    "error_code": null,
    "error_message": null
  },
  "usage": {
    "audio_count": 1,
    "input_chars_num": 36,
    "token_usage": {
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "total_tokens": 0
    }
  }
}

4.取消任务

shell

POST https://api.scnet.cn/api/llm/v1/tasks/{task_id}/cancel

仅非终态任务（pending、running 等）可以取消。已处于终态（succeeded、failed、cancelled）的任务无法取消。

4.1 请求参数

名称	类型	必填	示例值
Content-Type	string	是	application/json
Authorization	string	是	Bearer <API Key>

Path 参数

名称	类型	必填	描述
task_id	string	是	需要取消的音频合成任务 ID。

4.2 请求示例

cURL请求示例

shell

curl -X POST 'https://api.scnet.cn/api/llm/v1/tasks/<task_id>/cancel' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <API Key>'

4.3 响应示例

json

{
  "request_id": "5fe545a6c8fe2c6a",
  "output": {
    "task_id": "2062800436483940354",
    "task_status": "cancelled",
    "submit_time": "2026-06-05 15:35:23",
    "end_time": "2026-06-05 15:36:01",
    "results": null,
    "error_code": null,
    "error_message": null
  },
  "usage": null
}

对已处于终态的任务调用取消接口，将返回错误：

json

{
  "error": {
    "message": "task already in terminal status: cancelled",
    "type": "invalid_task_status",
    "param": null,
    "code": "422"
  },
  "request_id": "1533b3a078bf197e"
}

5.流式语音合成

在请求体中设置 stream_format 为 sse，服务端以 Server-Sent Events 形式分帧返回。每个 data: 帧为一段 JSON，音频增量以 base64 data URI 形式承载在 output.results 中；合成结束帧的 output.task_status 为 succeeded，并携带 usage 用量信息。

流式形态为实时直传，不创建异步任务，故 X-MultiModal-Async 对流式请求不生效。

5.1 请求示例

cURL请求示例

shell

curl -N -X POST 'https://api.scnet.cn/api/llm/v1/audios/generations' \
-H 'Content-Type: application/json' \
-H 'Accept: text/event-stream' \
-H 'Authorization: Bearer <API Key>' \
--data-raw '{
  "model": "Qwen3-TTS-Instruct-Flash",
  "stream_format": "sse",
  "input": {
    "text": "欢迎使用语音合成服务。",
    "voice": "Cherry"
  }
}'

5.2 响应示例（流式）

text

data: {"request_id":"93181007-6691-9bf8-810d-c04e37959265","output":{"task_status":"processing","results":["data:audio/wav;base64,UklGRiQ..."]}}

data: {"request_id":"93181007-6691-9bf8-810d-c04e37959265","output":{"task_status":"processing","results":["data:audio/wav;base64,AAAAAA..."]}}

data: {"request_id":"93181007-6691-9bf8-810d-c04e37959265","output":{"task_status":"succeeded"},"usage":{"audio_count":1,"input_chars_num":10,"token_usage":{"prompt_tokens":12,"completion_tokens":240,"total_tokens":252}}}

5.3 流式事件说明

task_status	描述
processing	音频合成中。`output.results` 携带本帧的 base64 音频增量（data URI），客户端可拼接或边收边播。
succeeded	合成结束帧。携带 `usage` 用量信息，不再包含音频增量。
failed	合成失败帧。携带 `output.error_code` 与 `output.error_message`。

6.任务状态说明

内部状态	说明	对外状态(apiStatus)	是否终态
PENDING	待执行	pending	否
PROCESSING	执行中	running	否
WAIT_PROVIDER_COMPLETED	等待 Provider 完成（轮询中）	running	否
UPLOADING	结果审核上传中	running	否
SUCCEEDED	成功	succeeded	是
FAILED	失败	failed	是
CANCELLED	已取消	cancelled	是

7.注意事项

input.text 与 input.voice 为必填项，缺失时返回参数错误。
非流式同步形态下，请求返回时直接携带合成音频地址，无需调用任务查询接口。
异步形态需在请求头中携带 X-MultiModal-Async: true，提交后通过任务查询接口获取合成结果。
流式形态需在请求头中携带 Accept: text/event-stream，并在请求体中设置 stream_format 为 sse。
计费维度：千问3-TTS-Flash 系列按输入字符数（input_chars_num）计量。

图像生成

视频生成

音频

接口说明 ​

语音合成 ​

1.功能介绍 ​

2.提交音频任务 ​

2.1 请求参数 ​

Header 参数 ​

Body 参数 ​

input 参数说明 ​

2.2 响应参数 ​

2.3 请求示例 ​

cURL请求示例 ​

Python请求示例 ​

2.4 响应示例 ​

同步出参 ​

异步出参（请求头携带 X-MultiModal-Async: true） ​

3.查询任务状态 ​

3.1 请求参数 ​

Header 参数 ​

Path 参数 ​

3.2 响应参数 ​

3.3 请求示例 ​

cURL请求示例 ​

Python请求示例 ​

3.4 响应示例 ​

4.取消任务 ​

4.1 请求参数 ​

Header 参数 ​

Path 参数 ​

4.2 请求示例 ​

cURL请求示例 ​

4.3 响应示例 ​

5.流式语音合成 ​

5.1 请求示例 ​

cURL请求示例 ​

5.2 响应示例（流式） ​

5.3 流式事件说明 ​

6.任务状态说明 ​

7.注意事项 ​

接口说明

语音合成

1.功能介绍

2.提交音频任务

2.1 请求参数

Header 参数

Body 参数

input 参数说明

2.2 响应参数

2.3 请求示例

cURL请求示例

Python请求示例

2.4 响应示例

同步出参

异步出参（请求头携带 X-MultiModal-Async: true）

3.查询任务状态

3.1 请求参数

Header 参数

Path 参数

3.2 响应参数

3.3 请求示例

cURL请求示例

Python请求示例

3.4 响应示例

4.取消任务

4.1 请求参数

Header 参数

Path 参数

4.2 请求示例

cURL请求示例

4.3 响应示例

5.流式语音合成

5.1 请求示例

cURL请求示例

5.2 响应示例（流式）

5.3 流式事件说明

6.任务状态说明

7.注意事项