音频生成 API

通过 POST /api/v1/speech 与 POST /api/v1/sound-effects 实现文本转语音和音效生成，以及公开的音色目录。

语音和音效会在请求返回前生成完毕：响应通常已带 status: "success"，音频 URL 在 data.taskUrls 中。请保持连接直到收到响应。返回的 data.id 同样可用于 GET /api/v1/tasks/{taskId}，便于统一轮询流程。

列出音色

GET /api/v1/voices 是公开端点（无需 API key），最多缓存一小时。

curl https://viewmax.studio/api/v1/voices

{
  "code": 0,
  "message": "ok",
  "data": {
    "default_model": "eleven_v3",
    "characters_per_credit": 20,
    "minimum_credits": 1,
    "voices": [
      {
        "id": "EXAVITQu4vr4xnSDxMaL",
        "name": "Sarah",
        "gender": "female",
        "language": "en",
        "languages": ["en", "fr", "ar", "zh", "es", "hi"],
        "accent": "american",
        "use_case": "entertainment_tv",
        "description": "Young adult woman with a confident and warm, mature quality and a reassuring, professional tone.",
        "preview_url": "https://…/preview.mp3",
        "recommended_model": "eleven_v3"
      }
    ]
  }
}

字段	说明
`default_model`	音色没有 `recommended_model` 时使用的模型
`characters_per_credit`	语音费用为 `max(minimum_credits, ceil(文本字符数 / characters_per_credit))`
`minimum_credits`	单次语音请求的最低价格
`voices[]`	`id`（作为 `voice_id` 发送）、`name`、`gender`、`language`、`languages`、`accent`、`use_case`、`description`、`preview_url`、`recommended_model`

文本转语音

POST /api/v1/speech 用所选音色将文本转为语音。费用为 max(1, ceil(字符数 / 20)) 积分，按去掉首尾空白后的文本计算：19 个字符为 1 积分，1,000 个字符为 50 积分。套餐额度不适用于 API 的语音生成。

字段	必填	类型	说明
`text`	是	string	非空的待朗读文本，首尾空白会被去掉
`voice_id`	是	string	来自 `GET /api/v1/voices` 的音色 `id`
`options`	否	object	见下表

选项	类型	说明
`model_id`	string	默认使用音色的 `recommended_model`。未知值会在提供方处失败（任务失败并退还积分）
`speed`	number	0.25–4；超出范围的值会被截断到边界
`stability`	number	0–1；超出范围的值会被截断到边界
`similarity_boost`	number	0–1；超出范围的值会被截断到边界

curl -X POST https://viewmax.studio/api/v1/speech \
  -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-001" \
  -d '{
    "text": "Welcome to ViewMax.",
    "voice_id": "EXAVITQu4vr4xnSDxMaL",
    "options": { "speed": 1.0 }
  }'

音效

POST /api/v1/sound-effects 根据文本提示生成音效，每次 5 积分。

字段	必填	类型	说明
`prompt`	是	string	非空的声音描述
`options`	否	object	见下表

选项	类型	说明
`duration_seconds`	number	0.5–22 之间的 JSON 数字
`prompt_influence`	number	0–1 之间的 JSON 数字

超出这些范围时会在扣费前返回 400。

curl -X POST https://viewmax.studio/api/v1/sound-effects \
  -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: thunder-001" \
  -d '{ "prompt": "A distant rolling thunder clap", "options": { "duration_seconds": 5 } }'

成功响应

语音示例：

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "9d1f3b5c-7e9a-4c2d-8f1b-3a5c7e9b1d24",
    "userId": "usr_123",
    "mediaType": "audio",
    "model": "eleven_v3",
    "prompt": "Welcome to ViewMax.",
    "options": "{\"voice_id\":\"EXAVITQu4vr4xnSDxMaL\",\"speed\":1}",
    "status": "success",
    "createdAt": "2026-09-29T08:00:00.000Z",
    "updatedAt": "2026-09-29T08:00:03.000Z",
    "deletedAt": null,
    "taskId": "sync:9d1f3b5c-7e9a-4c2d-8f1b-3a5c7e9b1d24",
    "taskInfo": null,
    "taskResult": "{\"output\":[\"https://cdn.example.com/audio/speech.mp3\"]}",
    "taskUrls": ["https://cdn.example.com/audio/speech.mp3"],
    "costCredits": 1,
    "scene": "text-to-speech",
    "visibility": "user",
    "creditId": "cr_246",
    "waivedCredits": 0,
    "fairUseKey": null
  }
}

音效返回相同结构，其中 scene 为 "text-to-sound-effects"，costCredits 为 5。字段说明见视频生成 API中的任务字段。taskUrls 始终是数组。

幂等与退款

发送 Idempotency-Key（1–200 个可见 ASCII 字符，不含空格）。重复使用同一个键会返回原任务及其 costCredits，不会再次扣费；服务端不比较请求体，同一账号的所有创建端点共用这些键。超时后用同一个键重试；有意发起新尝试时换用新键。不带该请求头时，每次 POST 都会创建新任务并扣费。
任务创建时扣除积分。余额低于费用时返回 402，不创建任务。以 failed 或 canceled 结束的任务会自动退还积分。

错误

所有错误都使用错误信封。

HTTP	`error.type`	`message` 示例	处理方式
400	`invalid_request`	`text is required` / `voice_id is required` / `prompt is required`	补充必填字段
400	`invalid_request`	`unknown voice_id: abc. Call GET /api/v1/voices (MCP: list_voices) for available voices.`	使用 `GET /api/v1/voices` 中的音色 `id`
400	`invalid_request`	`options.duration_seconds must be a number from 0.5 to 22`	发送范围内的 JSON 数字（音效）
400	`invalid_request`	`options.prompt_influence must be a number from 0 to 1`	发送范围内的 JSON 数字（音效）
400	`invalid_request`	`the generation request uses unsupported settings`，并带 `error.task_id`	提供方拒绝了这些设置，任务已失败并退还积分。读取该任务的 `taskInfo.errorMessage`，调整后用新键重试
400	`content_rejected`	`input content was rejected by safety filters`	修改文本或提示词，不要原样重试
402	`insufficient_credits`	`insufficient credits`	未创建任务。补充积分前不要重试
500	`internal_error`	`the generation service is temporarily unavailable`	带 `error.task_id` 时任务已失败并退还积分，可重试一次。若 hint 说明结果未知，请轮询该任务，不要重试
503	`internal_error`	—	仅音效：内容安全检查暂不可用，稍后重试

音频生成 API

列出音色

文本转语音

音效

成功响应

幂等与退款

错误

On this page