音乐生成 API

使用 POST /api/v1/music 生成音乐，包括选项、计价与错误处理。

创建音乐任务

POST /api/v1/music 根据文本提示生成原创音乐。音乐在请求返回前生成完毕，因此响应通常已带 status: "success"，音乐 URL 在 data.taskUrls 中；请保持连接并设置足够长的客户端超时。返回的 data.id 同样可用于 GET /api/v1/tasks/{taskId}，便于统一轮询流程。

POST https://viewmax.studio/api/v1/music
Authorization: Bearer sk-your-api-key
Content-Type: application/json
Idempotency-Key: lofi-001

请求体

字段	必填	类型	说明
`prompt`	是	string	非空的音乐描述
`options`	否	object	生成控制项

`options`

字段	类型	说明
`duration_seconds`	number	音乐时长（秒），取 3–300 的 JSON 数字，默认 60
`instrumental`	boolean	`true` 表示纯音乐，无人声
`style`	string	曲风或情绪。会改变 `prompt` 的解读方式，见下文
`title`	string	歌名。会改变 `prompt` 的解读方式，见下文
`lyrics`	string	要演唱的歌词

options.duration 和 options.music_length_ms 会被拒绝，请使用 duration_seconds。

设置了 style 或 title 时，模型会把 prompt 当作歌词。若要描述一首曲子，请把完整描述写在 prompt 中，并且不要设置 style 和 title。若要为歌曲指定曲风，请把歌词写在 prompt 中，且不要再传 lyrics。

计价

音乐费用为 max(60, ceil(duration_seconds)) 积分：60 秒以内 60 积分，超出部分每秒 1 积分（300 秒为 300 积分）。不传 duration_seconds 时生成 60 秒，消耗 60 积分。套餐额度不适用于 API 的音乐生成。GET /api/v1/models?type=music 中的 credits 为基础价格。

示例

curl -X POST https://viewmax.studio/api/v1/music \
  -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lofi-001" \
  -d '{
    "prompt": "Warm lo-fi hip-hop with a mellow piano loop",
    "options": { "duration_seconds": 30, "instrumental": true }
  }'

该请求消耗 60 积分。

成功响应

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "5c7e9a1b-3d5f-4b6c-8e0a-2f4b6d8e0a12",
    "userId": "usr_123",
    "mediaType": "music",
    "model": "music_v2",
    "prompt": "Warm lo-fi hip-hop with a mellow piano loop",
    "options": "{\"duration_seconds\":30,\"instrumental\":true}",
    "status": "success",
    "createdAt": "2026-09-29T08:00:00.000Z",
    "updatedAt": "2026-09-29T08:00:42.000Z",
    "deletedAt": null,
    "taskId": "sync:5c7e9a1b-3d5f-4b6c-8e0a-2f4b6d8e0a12",
    "taskInfo": null,
    "taskResult": "{\"output\":[\"https://cdn.example.com/music/track.mp3\"]}",
    "taskUrls": ["https://cdn.example.com/music/track.mp3"],
    "costCredits": 60,
    "scene": "text-to-music",
    "visibility": "user",
    "creditId": "cr_789",
    "waivedCredits": 0,
    "fairUseKey": null
  }
}

字段说明见视频生成 API中的任务字段。taskUrls 始终是数组。

幂等与退款

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

错误

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

HTTP	`error.type`	`message` 示例	处理方式
400	`invalid_request`	`prompt is required`	发送非空提示词
400	`invalid_request`	`options.duration_seconds must be a number from 3 to 300`	发送范围内的 JSON 数字
400	`invalid_request`	`options.duration is not supported; use options.duration_seconds`	改用 `duration_seconds`
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