控制台

YB Studio API 文档

开始接入OpenAPI ↗

生产 Base URL

https://ybstudio.cn/api

统一的异步生成接口

YB Studio 将声音与数字人能力收敛到一致的认证、任务和结果模型中。业务代码无需理解底层 Worker，只需提交任务、轮询状态并读取结果。

统一鉴权

外部程序使用可独立撤销的 API Key；第一方创作台使用同源 HttpOnly 会话。

异步任务

生成接口立即返回任务 ID，长耗时工作在 Worker 中执行，不阻塞请求。

可靠结算

提交时预扣积分，成功后按真实用量结算，失败自动退回预扣。

短时结果

结果通过短时签名地址下载，并明确返回服务端保留截止时间。

两种认证边界

网页用户与服务器程序使用不同凭证，但最终都会解析为同一个用户身份并执行相同的套餐、余额、速率限制和资源归属检查。

HttpOnly Session

YB Studio 第一方网页通过 HttpOnly 登录会话调用上传、TTS 与任务查询接口，页面脚本不会读取令牌。

X-API-Key / Bearer

外部程序使用 X-API-Key 或 Bearer API Key。密钥只在创建时展示，可在控制台独立撤销。

不要在浏览器代码中保存长期 API Key

浏览器创作台应使用登录会话；API Key 只应保存在你控制的服务器、密钥管理服务或受保护的 CI 环境变量中。

三步完成第一条 TTS 请求

创建 API Key 后提交文本，保存返回的任务 ID，再通过任务接口轮询到成功状态。

  1. 1在控制台创建 API Key
  2. 2提交带幂等键的生成请求
  3. 3轮询任务并获取结果
cURL
curl -X POST https://ybstudio.cn/api/v1/tts \
  -H "X-API-Key: yb_xxx_yyy" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tts-001" \
  -d '{
    "text": "你好，欢迎使用 YB Studio。",
    "use_emo_text": true,
    "emo_text": "温暖而平静",
    "emo_alpha": 0.7
  }'

任务生命周期

生成任务只使用离散状态，不伪造进度百分比。客户端应为 queued 与 processing 设置合理的轮询间隔。

  1. 1
    提交任务并预扣积分
  2. 2
    轮询 queued / processing
  3. 3
    成功后获取短时下载地址
  4. 4
    失败自动退回预扣积分

接口参考

下面的字段和示例来自当前生产 API 契约。机器生成客户端应优先使用 OpenAPI 文件。

POST/v1/uploads

申请上传地址

为声音、情绪或数字人素材创建短时预签名 PUT 地址。当前创作台只接受不超过 20 MiB 的 WAV 声音样本。

请求字段

filename必填

原始文件名，用于安全推导对象扩展名。

content_type可选

素材 MIME；声音创作台使用 audio/wav。

size_bytes可选

声明的文件字节数；浏览器会话上传时必填。

purpose可选

voice_reference 或 emotion_reference；浏览器会话上传时必填。

rights_confirmed可选

确认拥有声音使用权；会话声音上传时必须为 true。

请求示例
curl -X POST https://ybstudio.cn/api/v1/uploads \
  -H "X-API-Key: yb_xxx_yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "voice.wav",
    "content_type": "audio/wav",
    "size_bytes": 1048576,
    "purpose": "voice_reference",
    "rights_confirmed": true
  }'
响应示例
{
  "asset_id": "asset_xxx",
  "object_key": "inputs/user-id/voice.wav",
  "upload_url": "https://storage.example/…",
  "expires_in": 900,
  "delete_after": "2026-08-19T14:00:00Z"
}
POST/v1/tts

创建文本转语音任务

使用系统预置音色、默认音色或已上传的声音引用生成语音，并可通过情绪文本、参考音频或八维向量调整表达。

请求字段

text必填

要合成的内容，最多 5000 个字符。

voice_preset_id可选

系统预置音色 ID，可从 /voice-presets 获取；不会暴露私有对象路径。

voice_ref_key可选

属于当前用户的声音参考对象键；省略时使用默认音色。

emo_ref_key可选

属于当前用户的情绪参考音频对象键。

emo_text可选

自然语言情绪描述，与 use_emo_text 配合使用。

emo_alpha可选

情绪强度，取值由当前模型约束。

emo_vector可选

八维情绪控制向量。

请求示例
curl -X POST https://ybstudio.cn/api/v1/tts \
  -H "X-API-Key: yb_xxx_yyy" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tts-001" \
  -d '{
    "text": "你好，欢迎使用 YB Studio。",
    "use_emo_text": true,
    "emo_text": "温暖而平静",
    "emo_alpha": 0.7
  }'
响应示例
{
  "id": "job_xxx",
  "type": "tts",
  "status": "queued",
  "reserved_credits": 12,
  "estimate_detail": {}
}
POST/v1/avatar

创建音频驱动数字人任务

使用已上传的音频驱动人物图像生成数字人视频。套餐、并发与 720p 权限仍由服务器校验。

请求字段

audio_ref_key必填

属于当前用户的驱动音频对象键。

image_ref_key可选

属于当前用户的人物图像对象键。

resolution可选

请求的输出分辨率；是否允许 720p 取决于套餐。

prompt可选

可选的生成提示信息。

请求示例
curl -X POST https://ybstudio.cn/api/v1/avatar \
  -H "X-API-Key: yb_xxx_yyy" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: avatar-001" \
  -d '{
    "audio_ref_key": "inputs/user-id/speech.wav",
    "image_ref_key": "inputs/user-id/portrait.png"
  }'
响应示例
{
  "id": "job_xxx",
  "type": "avatar",
  "status": "queued"
}
POST/v1/avatar/from-text

创建文本直达视频任务

在同一任务中完成语音生成与数字人视频生成，适合口播内容的服务器端自动化流程。

请求字段

text必填

用于生成语音和驱动视频的口播文本。

image_ref_key可选

属于当前用户的人物图像对象键。

voice_ref_key可选

可选声音引用；省略时使用默认音色。

resolution可选

请求的输出分辨率。

请求示例
curl -X POST https://ybstudio.cn/api/v1/avatar/from-text \
  -H "X-API-Key: yb_xxx_yyy" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: avatar-text-001" \
  -d '{"text":"你好，欢迎使用 YB Studio。"}'
响应示例
{
  "id": "job_xxx",
  "type": "avatar_from_text",
  "status": "queued"
}
GET/v1/jobs/{id}

查询任务状态

读取当前用户任务的 queued、processing、succeeded 或 failed 状态，以及最终错误信息和结算结果。

请求字段

id必填

创建任务后返回的任务 ID，放在 URL 路径中。

请求示例
curl https://ybstudio.cn/api/v1/jobs/job_xxx \
  -H "X-API-Key: yb_xxx_yyy"
响应示例
{
  "id": "job_xxx",
  "status": "processing",
  "progress": null,
  "error": null
}
GET/v1/jobs/{id}/result

获取任务结果

任务成功后获取短时下载地址、有效秒数与媒体保留截止时间；地址过期后可再次请求。

请求字段

id必填

已成功任务的 ID，放在 URL 路径中。

请求示例
curl https://ybstudio.cn/api/v1/jobs/job_xxx/result \
  -H "X-API-Key: yb_xxx_yyy"
响应示例
{
  "result_url": "https://storage.example/…",
  "expires_in": 900,
  "retained_until": "2026-08-25T14:00:00Z"
}

计费、积分退回与幂等

同一个业务动作不应因为网络重试而重复扣费。写请求应携带稳定且唯一的 Idempotency-Key。

  • ✓任务创建时预扣预计积分，成功后按真实用量结算。
  • ✓任务失败会自动退回预扣积分，不需要客户端发起操作。
  • ✓同一用户、同一路径与同一个幂等键会复用原任务语义。
  • ✓客户端超时后应先查询原任务，不要立即创建新的业务请求。

常见错误

所有错误都使用标准 HTTP 状态码和 JSON 错误结构。记录请求时间、路径与任务 ID，排查时不要记录完整密钥。

401

凭证缺失、过期或已撤销

402

积分余额不足，请先选择套餐或充值

403

套餐不支持、Origin 无效或资源不属于当前用户

422

文本、声音样本或生成参数不合法

503

功能维护、管理员关闭或没有 90 秒内在线的算力 Worker；WORKER_UNAVAILABLE 不会创建任务或预扣积分

开发者资源

网页文档面向人阅读；OpenAPI 与 LLM 文档保留为机器工具和自动化客户端的输入。

OpenAPI ↗

完整的路径、Schema、认证方式和响应定义。

llms.txt ↗

适合工具快速读取的精简 API 上下文。

llms-full.txt ↗

包含更完整接口说明的机器可读文本。

控制台 ↗

创建、查看和撤销你的独立 API Key。