语音、音效与转写

语音合成

POST /audio/generations 创建异步音频任务。Qwen3-TTS 类服务使用 text 和受控音色字段，而不是所有场景都使用 prompt。

{"model":"<TTS_MODEL_ALIAS>","text":"欢迎使用星海智算。","voiceMode":"text"}

模式	字段	提醒
普通朗读	`voiceMode=text`	不上传视频、不猜预计音频秒数。
内置音色	`voiceMode=custom_voice`，`speaker`	speaker 使用模型支持的枚举，例如服务允许时的 `serena`。
音色描述	`voiceMode=voice_design`，`instruct`	只在服务开放此模式时使用。

可用音色见音色目录与详情，以及目标服务的实际能力。音乐生成或其他音频模型按其请求合同选择参数，不复用 TTS 的字段猜测。

为视频生成音效

先以 video 字段上传受支持的视频，再向音效模型提交：

{"model":"<FOLEY_MODEL_ALIAS>","prompt":"与画面同步的脚步和衣物摩擦声","input_video_asset_id":"<VIDEO_ASSET_ID>"}

它生成音频，不自动替你把音轨合并回原视频。使用任务查询和下载，按真实 MIME 保存输出。

语音转写

Qwen3-ASR-1.7B 把音频转换为文字。调用 POST /audio/transcriptions，在本地文件和公网音频 URL之间选择一种输入即可。

这是同步接口：一次请求直接返回转写结果，不返回 jobId，无需轮询或下载任务结果。模型广场的「API 接入」可以根据所选音频来源生成 Python、JavaScript 和 cURL 示例。

1. 准备 API Key 和模型别名

在门户的 API Key 管理页创建有权调用目标服务的 Key，并确认账户余额。Key 仅放在服务端环境变量中，不要写入前端页面或公开仓库。其他 ASR 服务请使用对应模型卡片的别名。

export JUSP_BASE_URL="https://api.jusuanhub.com/v1"
export JUSP_MODEL="qwen3-asr-1.7b"
export JUSP_API_KEY="<YOUR_API_KEY>"

2. 选择一种音频来源

本地文件：multipart 上传

将 speech.wav 替换为运行命令的机器上可读取的音频路径。cURL 会读取文件并上传；不要手动设置 multipart 的 Content-Type，也不要把 Python bytes 放进 JSON。

curl --fail-with-body --max-time 300 "$JUSP_BASE_URL/audio/transcriptions" \
  -H "Authorization: Bearer $JUSP_API_KEY" \
  -F "model=$JUSP_MODEL" \
  -F "file=@speech.wav" \
  -F "response_format=json"

公网音频 URL：JSON 请求

将示例地址替换为实际可下载的音频 HTTPS 地址。地址应直接返回音频文件，无需 Cookie 或登录；可使用有效期内的签名 URL，并给下载和转写留足有效期。网页分享链接、私网地址、本机路径不能作为音频 URL。

curl --fail-with-body --max-time 300 "$JUSP_BASE_URL/audio/transcriptions" \
  -H "Authorization: Bearer $JUSP_API_KEY" \
  -H "Content-Type: application/json" \
  --data "{\"model\":\"$JUSP_MODEL\",\"input_audio_url\":\"https://example.com/speech.wav\",\"response_format\":\"json\"}"

file 与 input_audio_url 必须且只能提供一项。URL 模式由平台下载音频，再校验实际格式、大小和时长；它不会绕过文件输入限制，也不需要先调用素材上传接口。

3. 读取转写结果

默认使用 JSON。下面是结构示例，文字和时长以实际音频为准；其他字段按目标服务能力返回。

{"text":"欢迎使用语音转写。","language":"Chinese","duration":3.2}

从 text 读取转写文字。Qwen3-ASR-1.7B 也支持 response_format=text，此时响应体是纯文本，不能调用 response.json()。

以下 Python 示例使用 URL 输入。先安装 requests，并沿用前面的环境变量：

import os
import requests

response = requests.post(
    f"{os.environ['JUSP_BASE_URL'].rstrip('/')}/audio/transcriptions",
    headers={"Authorization": f"Bearer {os.environ['JUSP_API_KEY']}"},
    json={
        "model": os.environ["JUSP_MODEL"],
        "input_audio_url": "https://example.com/speech.wav",
        "response_format": "json",
    },
    timeout=300,
)
response.raise_for_status()
print(response.json()["text"])

输入限制与可选参数

Qwen3-ASR-1.7B 的当前输入限制为：单个非空音频不超过 25 MiB、300 秒。常见格式包括 WAV、MP3、M4A、AAC、WebM、OGG 和 FLAC；文件内容必须与声明格式相符。其他模型以模型卡片和服务能力为准。

参数	用法
`model`	必填，目标服务的公开模型别名。
`file`	本地文件模式必填，通过 multipart 上传一个文件。
`input_audio_url`	URL 模式必填，通过 JSON 提交公网 HTTPS 音频地址。不能同时提供 `file`。
`language`	可选，省略时自动识别；仅使用目标模型支持的语言值。
`response_format`	Qwen3-ASR-1.7B 支持 `json`（默认）或 `text`。

语音转写按音频时长计量，计费秒数向上取整；单价以模型卡片当前价格为准。

调用失败时如何处理

400 / 422：检查是否遗漏音频来源、同时提供两种来源、使用不支持的参数或格式；URL 是否能直接下载实际音频。
401 / 403：检查 API Key 是否有效，以及是否有目标服务的调用权限。
402：检查账户可用余额。
413：音频或请求超过大小限制，请缩小输入。
429 / 5xx / 客户端超时：保留响应中的请求标识并排查调用记录。同步转写没有任务轮询接口；结果未知时不要自动重复提交，避免重复计费。

更多鉴权与排查方式见首次调用和错误处理。

语音、音效与转写

本页目录