Seedance API 文档
快速开始 价格 llms.txt
控制台
Seedance · Seedream · Upscaler · Seed Audio · Zhenzhen · Suno · Midjourney

几行代码，生成 AI 视频、图片与音频

本服务提供异步任务接口，用于调用 Seedance 2.0 视频、视频超分、 Seedream V5 Pro / V5 Flash 图片、Doubao Seed Audio 音频、Zhenzhen 扩展、Suno 音乐与 Midjourney模型： 提交任务后轮询结果即可拿到媒体直链，按实际上游消耗计费，失败全额退款。

🎬 视频三种方式
文生视频（t2v）、图生视频（i2v，支持首尾帧）、多模态视频（multi，图片 + 视频 + 音频混合参考）。
⬆️ 视频超分
把已有 MP4 提升到 720p / 1080p / 2k / 4k；模型 zhenzhen-upscaler，按输入时长 × 目标分辨率计费。
🖼️ Seedream 图片
文生图（t2i）、图生图（i2i）与图层拆分；V5 Flash 支持 1k / 1.5k / 2k 或自定义宽高，输出 JPEG / PNG。
🔊 Seed Audio
异步音频生成：文本提示词 + 可选音色 / 参考音频 / 参考图；按输出时长计费。
🎵 Suno 音乐
31 个音乐 action：文生曲、续写、翻唱、分轨等；走 /v1/music/*，按上游 cost(USD) 结算。
🎨 Midjourney
Imagine / Upscale / Variation / Video 等；走 /v1/midjourney/*，按上游 cost(USD) 结算。

接口总览

POST /v2/video_generation MiniMax-H3 · MiniMax V2 格式 POST /v1/videos 提交视频生成任务 GET /v1/videos/{task_id} 查询视频任务状态与结果 POST /v1/videos · 超分 视频超分（zhenzhen-upscaler） POST /v1/image/generations 提交图片生成任务 GET /v1/image/generations/{task_id} 查询图片任务状态与结果 POST /v1/3d/generations 提交混元文生 / 图生 3D 任务 POST /v1/audio/generations 提交音频生成任务 GET /v1/audio/generations/{task_id} 查询音频任务状态与结果 POST /v1/music/generations[/:action] 提交 Suno 音乐任务 GET /v1/music/tasks/{task_id} 查询 Suno 音乐任务 POST /v1/midjourney/generations[/:action] 提交 Midjourney 任务 GET /v1/midjourney/tasks/{task_id} 查询 Midjourney 任务 POST /v1/chat/completions 文本对话（同步，DeepSeek / Qwen / GLM / GPT / Kimi） POST /v1/audio/transcriptions 语音转写（同步，whisper-1） POST /v1/files/upload 上传参考素材，换取 24 小时直链 GET /api/usage/wallet/ 查询账户钱包余额

Base URL 统一为 https://api.seedance.nz。

ℹ

站点同时保留旧版端点 POST /v1/video/generations + GET /v1/video/generations/{task_id}（请求体格式相同，查询响应字段不同）。新接入请统一使用 /v1/videos，旧端点仅为兼容保留。

🤖

用 AI 编程工具接入？本文档提供 AI 友好的 Markdown 版：https://api.seedance.nz/docs/llms.txt。把这个链接直接发给 Cursor、Claude Code、Codex 等工具，或将内容粘贴到对话中，AI 即可获得完整的接口定义、参数说明、价格表与实现要点，一次性生成正确的接入代码。

异步任务实际扣费

所有异步生成任务在完成最终结算后，查询接口都会返回公开的 usage 对象：

终态响应片段
{
  "usage": {
    "amount": 8.75,
    "currency": "CNY"
  }
}
✓

amount 必须与本次任务最终实际从用户余额扣除的钱完全一致，单位由 currency 指明；它不是提交任务时的预扣金额。任务失败并已退款时，amount 为 0。

只有任务进入终态并完成多退少补后，usage 才代表最终实扣。

不同查询协议中的位置

查询接口读取位置
通用图片、视频、音频、3D 任务查询data.usage
GET /v1/music/tasks/{task_id}data.usage
GET /v1/midjourney/tasks/{task_id}usage
GET /v1/videos/{task_id}usage
GET /v2/query/video_generation/{task_id}task.usage

快速开始

三步跑通第一个视频生成任务。

1

获取 API Key

登录 控制台 → 「API 令牌」→ 新建令牌，得到形如 sk-xxxx 的 API Key。

2

提交任务

以最便宜的 seedance-2.0-mini-t2v（文生视频）为例：

终端
curl -X POST https://api.seedance.nz/v1/videos \
 -H "Authorization: Bearer $SEEDANCE_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "model": "seedance-2.0-mini-t2v",
 "prompt": "a calm lake at sunrise, cinematic light",
 "seconds": "5",
 "metadata": { "resolution": "480p" }
 }'
submit.py
import requests

resp = requests.post(
 "https://api.seedance.nz/v1/videos",
 headers={"Authorization": "Bearer sk-xxxx"},
 json={
 "model": "seedance-2.0-mini-t2v",
 "prompt": "a calm lake at sunrise, cinematic light",
 "seconds": "5",
 "metadata": {"resolution": "480p"},
 },
)
resp.raise_for_status()
task_id = resp.json()["id"]
print(task_id)
submit.mjs
const resp = await fetch("https://api.seedance.nz/v1/videos", {
 method: "POST",
 headers: {
 Authorization: "Bearer sk-xxxx",
 "Content-Type": "application/json",
 },
 body: JSON.stringify({
 model: "seedance-2.0-mini-t2v",
 prompt: "a calm lake at sunrise, cinematic light",
 seconds: "5",
 metadata: { resolution: "480p" },
 }),
});
const { id: taskId } = await resp.json();
console.log(taskId);

提交成功立即返回任务 ID，status 初始为 queued：

响应 · 200
{
 "id": "task_xxxxxxxxxxxx",
 "object": "video",
 "model": "seedance-2.0-mini-t2v",
 "status": "queued",
 "progress": 0,
 "created_at": 1783377182
}
⚠

Windows PowerShell 用户：请把 JSON 写入文件后用 --data-binary "@request.json" 提交。直接在命令行拼接带空格的 JSON 会被拆成多个参数，导致请求失败。

3

轮询任务结果

用任务 ID 每 3~5 秒查询一次，直到 status 变为 completed 或 failed：

终端
curl https://api.seedance.nz/v1/videos/task_xxxxxxxxxxxx \
 -H "Authorization: Bearer $SEEDANCE_API_KEY"
poll.py
import time
import requests

headers = {"Authorization": "Bearer sk-xxxx"}
while True:
 result = requests.get(
 f"https://api.seedance.nz/v1/videos/{task_id}", headers=headers
 ).json()
 if result["status"] in ("completed", "failed"):
 break
 time.sleep(3)

print(result.get("metadata", {}).get("url") or result.get("error"))
poll.mjs
const headers = { Authorization: "Bearer sk-xxxx" };
let result;
do {
 await new Promise((r) => setTimeout(r, 3000));
 const resp = await fetch(
 `https://api.seedance.nz/v1/videos/${taskId}`, { headers }
 );
 result = await resp.json();
} while (!["completed", "failed"].includes(result.status));

console.log(result.metadata?.url ?? result.error);

任务成功后 metadata.url 即为视频直链：

响应 · 生成成功
{
 "id": "task_xxxxxxxxxxxx",
 "object": "video",
 "model": "seedance-2.0-mini-t2v",
 "status": "completed",
 "progress": 100,
 "created_at": 1783377182,
 "completed_at": 1783377298,
 "metadata": { "url": "https://.../output.mp4?X-Tos-Signature=..." }
}
⚠

视频直链是带签名有效期的临时地址，请在拿到结果后及时下载转存到自己的存储。

鉴权

所有接口均使用 Bearer Token 鉴权，在请求头中携带控制台创建的 API Key：

HTTP Header
Authorization: Bearer sk-xxxxxxxxxxxx

缺少或格式错误的 Authorization 头会返回 401。API Key 等同于账户余额凭证，请勿写入前端代码或公开仓库。

查询钱包余额

GET /api/usage/wallet/ 用 API Key 查询账户钱包余额（非令牌额度）

返回当前 API Key 所属用户账户的钱包余额。与 /api/usage/token/（令牌剩余额度）不同：本接口查的是控制台「钱包」里的账户余额。

ℹ

amount 为按站点展示货币换算后的余额（本站通常为人民币）；quota / total_available 为内部额度单位。对接业务逻辑时优先使用 amount。

请求

仅需鉴权头，无 Body / Query 参数。

终端
curl https://api.seedance.nz/api/usage/wallet/ \
 -H "Authorization: Bearer $SEEDANCE_API_KEY"

响应字段

data
amountnumber
钱包剩余余额（按 display_type 换算后的展示值）。
used_amountnumber
累计已用量（展示值）。
quotainteger
钱包剩余额度（内部单位），与 total_available 相同。
used_quotainteger
累计已用额度（内部单位）。
display_typestring
展示类型，如 CNY / USD / TOKENS。
usernamestring
账户用户名。
groupstring
用户分组。
响应 · 200
{
 "code": true,
 "message": "ok",
 "data": {
 "object": "wallet_balance",
 "quota": 1500000,
 "used_quota": 250000,
 "total_available": 1500000,
 "amount": 3.0,
 "used_amount": 0.5,
 "display_type": "CNY",
 "username": "demo",
 "group": "default"
 }
}

MiniMax-H3 · MiniMax V2 格式

MiniMax-H3 支持文生视频、首帧/尾帧/首尾帧、多模态参考视频与独立驱动音频，使用本站 API Key。MiniMax V2 客户端替换 Base URL 为 https://api.seedance.nz，并按本节支持范围调整参数。

完整调用指南与 Python 示例 · 下载 OpenAPI JSON

ℹ

本服务支持视频生成，480P、1080P、drive_audio、audio_control 和最长 60 秒驱动音频属于扩展。当前不提供官方 2K、Context-IR 或再生成能力。参考站的 target / conditions / OSS PUT SPI 不能作为本接口请求体。

方法路径响应
POST/v2/video_generation{"task_id":"..."}
GET/v2/query/video_generation/{task_id}{"task":{...}}
GET/v2/query/video_generation{"items":[...],"total":1}
DELETE/v2/video_generation/{task_id}删除终态记录；取消必须得到上游确认

价格与参数

分辨率元/秒5 秒10 秒15 秒
480P0.150.751.502.25
768P0.301.503.004.50
1080P0.452.254.506.75

1080P 保留原生对齐尺寸，16:9 输出 1920×1088。

按请求输出秒数计算标准零售价，参考媒体不另收费。普通任务整数 4–15 秒；有独立驱动音频时整数 4–60 秒。账户实际价格以适用分组和折扣为准。

字段要求
model必填，精确名称 MiniMax-H3
content必填，至少一个非空 text，拼接后最多 10000 字符；最多 9 参考图、3 参考音频、3 视频和额外 1 条驱动音频；也可用独立首尾帧模式
resolution必填，480P / 768P / 1080P，也接受小写
duration必填整数秒数，普通 4–15；有 drive_audio 时 4–60
ratio1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 9:16 / 16:9 / 21:9。纯文本必填；参考省略时 16:9；首/尾帧可用 adaptive / auto 选择最近固定比例
audio_controlmode=native/lock_source/remix_source/reference_only；denoise_strength 0–1；add_drive_as_reference 布尔。非 native 模式要求驱动音频
callback_url可选 HTTPS 地址，仅 443 端口；先验证 challenge，再通知终态

文生视频

cURL
curl https://api.seedance.nz/v2/video_generation \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
   "model": "MiniMax-H3",
   "content": [{"type":"text","text":"航拍晨光中的山谷，镜头平稳前进。"}],
   "resolution": "480P",
   "duration": 5,
   "ratio": "16:9"
 }'

HTTP 200 返回 task_id 后，使用同一个 Key 查询 GET /v2/query/video_generation/{task_id}。成功读取 task.content.url，无需旧版 file_id 检索。状态为 queued、running、succeeded、failed、cancelled。

首帧、尾帧与首尾帧

JSON
{
  "model":"MiniMax-H3",
  "content":[
    {"type":"text","text":"人物自然转身，平稳过渡到尾帧构图。"},
    {"type":"image_url","image_url":{"url":"https://example.com/start.jpg"},"role":"first_frame"},
    {"type":"image_url","image_url":{"url":"https://example.com/end.jpg"},"role":"last_frame"}
  ],
  "resolution":"768P", "duration":5, "ratio":"adaptive"
}

省略尾帧项即可首帧生成，省略首帧项即可尾帧生成；图片省略 role 时也视为首帧。首尾帧还可与参考图片、音频、视频或驱动音频混用，各类上限独立计数，这是本服务扩展。自适应按首帧（仅有尾帧时按尾帧）选择最接近的 固定比例，不保证任意原图比例的精确输出。

参考图片、视频、声音与驱动音频

JSON
{
  "model": "MiniMax-H3",
  "content": [
    {"type":"text","text":"参考图中的人物面对镜头，口型跟随驱动音频，说出明文台词。"},
    {"type":"image_url","image_url":{"url":"https://example.com/person.jpg"},"role":"reference_image"},
    {"type":"audio_url","audio_url":{"url":"https://example.com/dialogue.wav"},"role":"drive_audio"}
  ],
  "resolution": "768P", "duration": 5, "ratio": "16:9",
  "audio_control": {"mode":"lock_source","denoise_strength":0,"add_drive_as_reference":true}
}

参考视频使用 type=video_url、video_url.url、role=reference_video；可在内容项顶层加 start_time_seconds，按 24 FPS 换算起始帧。参考声音使用 type=audio_url、audio_url.url、role=reference_audio，与独立 drive_audio 分开计数。每条参考视频（包括偏移后的素材）需为 2–15 秒。媒体可先调用本站 素材上传接口取得 URL。

有驱动音频时默认 lock_source + denoise_strength=0 + add_drive_as_reference=true；无驱动时默认 native + 0.35 + false。remix_source 可调去噪 0–1；需要独立参考音色时可把驱动作为参考设为 false。reference_only 必须有驱动，驱动作为参考省略时为 true，显式 false 报错。native 也可附带驱动，是否作为参考由该布尔参数决定。显式 0 和 false 均会保留。

ℹ

seed、采样步数与 flow shift 不对外开放。参考场景默认 16:9，显式 adaptive / auto 会报错；关键帧提供最近固定比例的自适应，也执行用户指定的固定比例，这些行为与官方有差异。480P、2:3/3:2、关键帧与参考素材混合、驱动控制和视频起始偏移是本服务扩展。当前 该接口不提供官方格式媒体用量，任务响应省略 usage；输出按 17n+5 帧对齐可能略长，仍按请求秒数计费。

任务管理、回调与错误

列表查询最近 7 天，支持 page_num（默认 1，最多 10000）、page_size（默认 10，最多 100）及 filter.status、重复的 filter.task_ids（最多 100 个）、filter.model、filter.task_type=generation。成功/失败记录可删除，也允许删除已取消记录（扩展），不会重复退款。服务无法确认排队取消时返回错误，原任务继续，不会提前退款。

回调先 POST {"challenge":"..."}，3 秒内以 HTTP 200 返回相同 JSON challenge 或纯文本。终态通知使用查询响应格式，收到任意 2xx 即视为送达，最多尝试 5 次，失败后等待 1/2/4/8 分钟。请按任务 ID 和状态幂等消费。中间状态推送不作保证。

错误示例
{"type":"error","error":{"type":"bad_request_error","message":"invalid request parameters","http_code":"400"},"request_id":"..."}

HTTP 错误与 HTTP 200 内的 task.error 不同。建议每 5–10 秒轮询；创建超时不代表未创建，不要无条件重发付费任务。提交结果不确定的错误响应如带 X-Task-Id，请保存它并查询已有任务；此时保留预扣，后台尝试从 bridge 恢复，不保证上游 ID 已丢失的任务可找回。完整示例、素材上传、错误处理与官方参考链接见 完整指南。

主、备用凭据按固定顺序调用；仅在未取得任务编号且上游明确拒绝（HTTP 401/402/403/429 或非零业务错误码）时切换一次。已受理任务及超时、5xx、无效 JSON 不自动重建；两次均被拒绝时保留最后错误，仅容量限制归为 429。

提交视频任务

POST /v1/videos 创建异步视频生成任务，立即返回任务 ID

请求体

Body 参数 · application/json
modelstring必填
模型名，如 seedance-2.0-mini-t2v，完整列表见 模型列表。模型名后缀决定任务类型：-t2v 文生视频 / -i2v 图生视频 / -multi 多模态视频。
promptstringt2v / multi 必填
文本提示词，最长 20480 字符；-i2v 模型可选。多模态场景可用 @Image 1、@Video 1 指代第几个参考素材，例如「把 @Video 1 中的人物替换成 @Image 1 中的人物」。
imagesstring[]i2v 必填
参考图片 URL 数组，仅 -i2v 模型使用。传 1 张为首帧图；传 2 张时第 2 张作为尾帧图。也可用单数字段 image（单个 URL 字符串）代替。JPG / JPEG / PNG / WEBP，单张 ≤ 30MB。
secondsstring可选
视频时长（秒）。可选 "4" ~ "15" 的整数，或 "-1" 让模型智能选择时长。默认 "5"。
metadataobject可选
生成参数集合，所有字段均可选：
resolutionstring
输出分辨率。Standard 档可选 480p / 720p / 1080p / 2k / 4k / native1080p / native4k；Fast、Mini 档可选 480p / 720p / 1080p / 2k / 4k。默认 720p。注意 1080p / 2k / 4k 为超分档，另收附加费，见 价格。
ratiostring
画面比例，可选 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9。默认 adaptive（自适应）。
seedinteger
随机种子，取值 -1 ~ 2147483647。默认 -1（随机）。
generate_audioboolean
是否生成配音 / 音效。默认 true。
return_last_frameboolean
是否额外返回视频最后一帧图片。默认 false。
contentarray
仅 -multi 模型使用，传入图片 / 视频 / 音频参考素材数组，结构见下方「多模态素材」。

各任务类型的用法与素材限制

任务类型传参方式素材限制
-t2v 文生视频 只传 prompt 无素材
-i2v 图生视频 prompt（可选）+ 顶层 images 图片 1~2 张：第 1 张为首帧（必填），第 2 张为尾帧（可选）。JPG / JPEG / PNG / WEBP，单张 ≤ 30MB
-multi 多模态视频 prompt（必填）+ metadata.content 图片 ≤ 9 张（JPG / JPEG / PNG / WEBP，单张 ≤ 30MB）；视频 ≤ 3 个（MP4，单个 ≤ 50MB）；音频 ≤ 3 个（MP3 / WAV，单个 ≤ 50MB，国内版 Fast 档 ≤ 15MB）。三类可混合，至少提供 1 个参考素材

多模态素材（metadata.content）

数组中每个元素按 type 区分三种素材：

image_url参考图片
{ "type": "image_url", "image_url": { "url": "https://..." } }
video_url参考视频
{ "type": "video_url", "video_url": { "url": "https://..." } } —— 传入参考视频后，整个任务按「有参考视频」的更低 Token 单价档计费，见 价格。
audio_url参考音频
{ "type": "audio_url", "audio_url": { "url": "https://..." } }
⚠

一旦传了 metadata.content，它会整体覆盖顶层 images 的效果。多模态场景请把图片也一并写进 content 数组，不要再单独传顶层 images。

多模态完整示例（1 张图 + 1 个视频，把视频中的人物换成图片中的人物）：

请求体 · seedance-2.0-standard-multi
{
 "model": "seedance-2.0-standard-multi",
 "prompt": "把 @Video 1 中的人物替换成 @Image 1 中的人物",
 "seconds": "5",
 "metadata": {
 "resolution": "1080p",
 "content": [
 { "type": "image_url", "image_url": { "url": "https://your-cdn.example.com/person.png" } },
 { "type": "video_url", "video_url": { "url": "https://your-cdn.example.com/source.mp4" } }
 ]
 }
}

响应

提交成功返回 200，任务进入队列：

响应 · 200
{
 "id": "task_xxxxxxxxxxxx",
 "object": "video",
 "model": "seedance-2.0-mini-t2v",
 "status": "queued",
 "progress": 0,
 "created_at": 1783377182
}

查询任务结果

GET /v1/videos/{task_id} 查询任务状态、进度与生成结果

路径参数 task_id 为提交任务时返回的 id。建议每 3~5 秒轮询一次。

任务状态

status含义
queued排队中，尚未开始处理
in_progress生成中，progress 为 0~100 的进度百分比
completed生成成功，metadata.url 为视频直链
failed生成失败，详见 error.code / error.message，费用全额退还

响应示例

响应 · in_progress
{
 "id": "task_xxxxxxxxxxxx",
 "object": "video",
 "model": "seedance-2.0-mini-t2v",
 "status": "in_progress",
 "progress": 50,
 "created_at": 1783377182,
 "metadata": { "url": "" }
}
响应 · completed
{
 "id": "task_xxxxxxxxxxxx",
 "object": "video",
 "model": "seedance-2.0-mini-t2v",
 "status": "completed",
 "progress": 100,
 "created_at": 1783377182,
 "completed_at": 1783377298,
 "metadata": { "url": "https://.../output.mp4?X-Tos-Signature=..." }
}
响应 · failed
{
 "id": "task_xxxxxxxxxxxx",
 "object": "video",
 "model": "seedance-2.0-mini-t2v",
 "status": "failed",
 "progress": 100,
 "error": {
 "code": "video_generation_failed",
 "message": "..."
 }
}

提交图片任务

POST /v1/image/generations 提交 Seedream V5 Pro / V5 Flash 异步图片生成或图层拆分任务

与视频接口一样采用「提交 → 轮询」异步模式。当前支持文生图（t2i）、图生图（i2i）与图层拆分。

请求体字段

Body · application/json
modelstring必填
Seedream V5 Pro：seedream-v5-pro-* / dola-seedream-5.0-pro-*；V5 Flash：seedream-v5-flash-* / dola-seedream-5.0-flash-*（均有 t2i、i2i、layer-decomposition）；千问：qwen-image-3.0-* / qwen-image-3.0-pro-* / qwen-image-3.0-global-*；Zhenzhen Image G-2：zhenzhen-image-g2-t2i / zhenzhen-image-g2-i2i（resolution 仅 1k）；Zhenzhen 扩展：zhenzhen-image-g-v2-lowprice / zhenzhen-image-gk-v15 / zhenzhen-image-gk-v15-edit / zhenzhen-image-gk-v2 / zhenzhen-image-gk-v2-edit / zhenzhen-image-nb-* / flux-3-image。
promptstring视模型
V5 Pro 普通生成 5 ~ 2000 字符；V5 Flash 文生图/图生图 5 ~ 5000 字符；图层拆分可选，0 ~ 2000 字符。
imagesstring[]i2i / 图层拆分必填
V5 Pro 图生图最多 10 张，单张 ≤10MB；V5 Flash 图生图 1 ~ 10 张，单张 ≤30MB；图层拆分必须恰好 1 张，≤30MB。也可用单数字段 image。可用 上传接口 换取直链。
metadataobject可选
图片参数集合，见下表。

metadata 字段

metadata
resolutionstring可选
V5 Pro 普通生成：1k / 2k；V5 Flash 普通生成：1k / 1.5k / 2k；均优先于 width × height。图层拆分：auto / 1k / 1.5k / 2k。Zhenzhen Image G-2：仅 1k。zhenzhen-image-g-v2-lowprice：1k / 2k / 4k（zhenzhen-image-gk-* 无此字段）。
widthinteger可选
仅 Seedream 文生图/图生图，输出宽度 240 ~ 8192；未传 resolution 时生效。图层拆分不支持。
heightinteger可选
仅 Seedream 文生图/图生图，输出高度 240 ~ 8192；未传 resolution 时生效。图层拆分不支持。
output_formatstring可选
普通生成及图层拆分底图：jpeg / png；拆出的图层为 PNG。
文生图 · seedream-v5-pro-t2i
curl -X POST https://api.seedance.nz/v1/image/generations \
 -H "Authorization: Bearer $SEEDANCE_API_KEY" \
 -H "Content-Type: application/json" \
 --data-binary @- <<'EOF'
{
 "model": "seedream-v5-pro-t2i",
 "prompt": "高端护肤品电商主图，纯白柔光展台，玻璃精华瓶",
 "metadata": {
 "resolution": "2k",
 "output_format": "jpeg"
 }
}
EOF
图生图 · seedream-v5-pro-i2i
{
 "model": "seedream-v5-pro-i2i",
 "prompt": "横版复古馆藏风美妆宣传海报，藏青深蓝色哑光底",
 "images": ["https://your-cdn.example.com/ref.png"],
 "metadata": {
 "resolution": "1k",
 "output_format": "jpeg"
 }
}
图层拆分 · seedream-v5-pro-layer-decomposition
{
 "model": "seedream-v5-pro-layer-decomposition",
 "images": ["https://your-cdn.example.com/source.png"],
 "metadata": {
 "resolution": "auto",
 "output_format": "jpeg"
 }
}

Seedream V5 Flash 示例

下列为国内模型。海外站使用对应的 dola-seedream-5.0-flash-* 名称，参数限制相同。

文生图 · seedream-v5-flash-t2i
{
 "model": "seedream-v5-flash-t2i",
 "prompt": "雨后街角的咖啡店，暖色灯光",
 "metadata": { "resolution": "1.5k", "output_format": "jpeg" }
}
图生图 · seedream-v5-flash-i2i
{
 "model": "seedream-v5-flash-i2i",
 "prompt": "将背景改为雨后街景",
 "images": ["https://your-cdn.example.com/ref.png"],
 "metadata": { "resolution": "1k", "output_format": "png" }
}
图层拆分 · seedream-v5-flash-layer-decomposition
{
 "model": "seedream-v5-flash-layer-decomposition",
 "images": ["https://your-cdn.example.com/source.png"],
 "metadata": { "resolution": "auto", "output_format": "jpeg" }
}

提交响应

响应 · 200
{
 "id": "task_xxxxxxxxxxxx",
 "task_id": "task_xxxxxxxxxxxx",
 "status": "queued",
 "model": "seedream-v5-pro-t2i",
 "created_at": 1783717700
}

查询图片任务

GET /v1/image/generations/{task_id} 查询图片任务状态与结果

建议每 3~5 秒轮询一次，直到 data.status 为 SUCCESS 或 FAILURE。成功时 data.result_url 是主图；图层拆分的全部底图/图层 URL 位于 data.data.content.image_urls（约 24 小时有效，请及时下载转存）。V5 Flash 两站一次成功探测均返回 JPEG 底图与 PNG 图层两项；该样本不保证每次的图层数量。当上游带元数据时，响应可选返回与 URL 顺序对齐的 data.data.content.layers，每项有 url，其余 outputType、size、text、zindex、boundingBox、description、name 为可选；仅有 URL 时省略该数组。

ℹ

图片查询接口返回通用任务记录结构（与视频的 OpenAI Video 风格响应不同）。请按下方字段读取。

status 取值（data.status）

status含义
NOT_START / SUBMITTED已提交，排队中
IN_PROGRESS生成中
SUCCESS成功，result_url 为图片直链
FAILURE失败，见 fail_reason，费用全额退还
终端
curl https://api.seedance.nz/v1/image/generations/task_xxxxxxxxxxxx \
 -H "Authorization: Bearer $SEEDANCE_API_KEY"
响应 · SUCCESS（节选）
{
 "code": "success",
 "data": {
 "task_id": "task_xxxxxxxxxxxx",
 "status": "SUCCESS",
 "progress": "100%",
 "result_url": "https://.../base.jpg",
 "quota": 270000,
 "data": {
 "status": "succeeded",
 "content": {
 "image_url": "https://.../base.jpg",
 "image_urls": ["https://.../base.jpg", "https://.../layer-1.png"]
 }
 }
 }
}

混元 3D v3.1

POST/v1/3d/generations提交文生 / 图生 3D 任务
GET/v1/3d/generations/{task_id}查询 3D 任务

模型：hunyuan3d-v3.1-text-to-3d（必填 prompt）或 hunyuan3d-v3.1-image-to-3d（images 1–8 张 JPG/PNG，顺序为正、左、右、后、上、下、左前、右前视图）。

可选参数：face_count 10000–1500000（默认 500000）、enable_pbr（默认 false）、generate_type（Normal / Geometry / Sketch）。成功后 data.result_url 与 data.data.content.file_url 返回 GLB 文件 URL，约 24 小时过期。

文生 3D
curl -X POST https://api.seedance.nz/v1/3d/generations \
 -H "Authorization: Bearer <API Key>" \
 -H "Content-Type: application/json" \
 --data-binary '{"model":"hunyuan3d-v3.1-text-to-3d","prompt":"一只青花陶瓷茶壶","face_count":500000,"enable_pbr":false,"generate_type":"Normal"}'

提交音频任务

POST /v1/audio/generations 提交 Doubao Seed Audio 异步音频生成任务

与图片接口一样采用「提交 → 轮询」异步模式。当前模型包含 Seed Audio、Mureka BGM/歌曲、MiniMax Speech 2.8/Voice Clone/Music 2.6 与 Qwen3 TTS。

ℹ

Mureka 伴奏模型要求 prompt 与 metadata.instrumental_id 二选一；metadata.n 为 1–3（默认 2，¥0.34/条），metadata.stream 默认 false。多结果时 result_url 为第一条，完整有序列表位于 data.content.audio_urls。

ℹ

本接口与 OpenAI 风格的同步 TTS POST /v1/audio/speech 不是同一条路径。Seed Audio 请使用 /v1/audio/generations。

请求体字段

Body · application/json
modelstring必填
doubao-seed-audio-1.0。
promptstring必填
音频生成提示词，长度 5 ~ 2048 字符（映射为上游 text_prompt）。
imagesstring[]可选
参考图片 URL（取首张 → 上游 image_url）。不可与 metadata.speaker 或参考音频同时使用。
metadataobject可选
音色、格式、语速等参数，见下表。

metadata 字段

metadata
speakerstring可选
音色 ID（豆包语音合成 2.0 / 声音复刻）。与参考音频、images 互斥。
audio_urlstring | string[]可选
参考音频 URL，最多 3 个（MP3 / WAV，单文件 ≤10MB）。也可用 audio_urls。与 speaker、images 互斥。
formatstring可选
输出格式，默认 wav。可选 wav / mp3 / pcm / ogg_opus。
sample_ratestring可选
采样率（Hz），默认 24000。可选 8000 / 16000 / 24000 / 32000 / 44100。
speech_rateinteger可选
语速，范围 -50 ~ 100（100=2.0×，-50=0.5×）。未传时服务端默认 0。
loudness_rateinteger可选
音量，范围 -50 ~ 100。未传默认 0。
pitch_rateinteger可选
音调，范围 -12 ~ 12。未传默认 0。
音色生成 · doubao-seed-audio-1.0
curl -X POST https://api.seedance.nz/v1/audio/generations \
 -H "Authorization: Bearer $SEEDANCE_API_KEY" \
 -H "Content-Type: application/json" \
 --data-binary @- <<'EOF'
{
 "model": "doubao-seed-audio-1.0",
 "prompt": "gentle rain falling on a quiet city street at night, soft ambient atmosphere",
 "metadata": {
 "speaker": "zh_male_shaonianzixin_uranus_bigtts",
 "format": "mp3",
 "sample_rate": "24000"
 }
}
EOF

提交响应

响应 · 200
{
 "id": "task_xxxxxxxxxxxx",
 "task_id": "task_xxxxxxxxxxxx",
 "status": "queued",
 "model": "doubao-seed-audio-1.0",
 "created_at": 1783870738
}

查询音频任务

GET /v1/audio/generations/{task_id} 查询音频任务状态与结果

建议每 3~5 秒轮询一次，直到 data.status 为 SUCCESS 或 FAILURE。成功时从 data.result_url 取音频直链（约 24 小时有效，请及时下载转存）。

ℹ

音频查询接口返回通用任务记录结构（与图片查询相同，与视频的 OpenAI Video 风格响应不同）。

status 取值（data.status）

status含义
NOT_START / SUBMITTED已提交，排队中
IN_PROGRESS生成中
SUCCESS成功，result_url 为音频直链
FAILURE失败，见 fail_reason，费用全额退还
终端
curl https://api.seedance.nz/v1/audio/generations/task_xxxxxxxxxxxx \
 -H "Authorization: Bearer $SEEDANCE_API_KEY"
响应 · SUCCESS（节选）
{
 "code": "success",
 "data": {
 "task_id": "task_xxxxxxxxxxxx",
 "status": "SUCCESS",
 "progress": "100%",
 "result_url": "https://.../output.mp3",
 "quota": 42000,
 "data": {
 "status": "succeeded",
 "content": {
 "audio_url": "https://.../output.mp3"
 }
 }
 }
}

文本对话（同步）

POST /v1/chat/completions OpenAI Chat Completions 兼容对话，同步/流式返回

模型：deepseek/deepseek-v4.1-flash、deepseek/deepseek-v4-flash-vision-exp、glm/glm-5.3-flash、glm-5.3、qwen/qwen3.8-flash-next、qwen/qwen3.8-max（Qwen 3.8 Max）、zhenzhen/gk-4.6（GK 4.6 海外版）、zhenzhen/g6-astra（GPT-6 Astra 节省版）、zhenzhen/g6-sol、zhenzhen/g6-luna、zhenzhen/g5.6-sol、zhenzhen/g5.6-terra、zhenzhen/g5.6-luna、zhenzhen/g5.5、zhenzhen/gm-3.8-flash、zhenzhen-op-5.5 与 kimi-k3（Kimi K3）。兼容 OpenAI Chat Completions 格式；支持 stream=true 流式输出。与异步图/视频任务接口不是同一路径。

DeepSeek V4.1 Flash 为 262,144 tokens 上下文，支持图片输入、工具调用、推理、流式输出、上下文缓存和结构化输出。价格以控制台为准。

DeepSeek Vision 实验版为 1,048,576 tokens 上下文，支持图片输入、工具调用、流式输出和结构化输出。实验版能力和价格可能调整，以控制台为准。

GLM/Qwen 两款 Flash 模型为 262,144 tokens 上下文，GLM-5.3 为 1,048,576 tokens。GLM-5.3 为纯文本输入、始终开启推理，工具选择仅支持 auto，不支持结构化输出；两款 Flash 模型支持视觉和结构化输出。价格以控制台为准。

ℹ

按 Token 用量结算（输入 / 输出倍率见定价页）。这些模型默认启用推理；回复中可能包含 reasoning_content，最终回答在 content。建议为短测试设置足够的 max_tokens（如 ≥256）。

ℹ

zhenzhen/gk-4.6 支持 500K 上下文、视觉输入、工具调用与推理。输入上下文少于 200K tokens 时，输入 / 输出 / 缓存读取分别为 ¥14 / ¥42 / ¥3.5 每 1M tokens；达到 200K 后分别为 ¥28 / ¥84 / ¥7。最终按海外上游返回的实际账单换算结算。

ℹ

zhenzhen/g6-astra 支持 1,050,000 tokens 上下文、视觉输入、工具调用、推理与流式输出。输入上下文不超过 272K tokens 时，输入 / 输出 / 缓存读取 / 缓存写入分别为 ¥28.82 / ¥144.12 / ¥2.88 / ¥36.03 每 1M tokens；超过 272K 后分别为 ¥57.65 / ¥216.18 / ¥5.76 / ¥72.06。最终按海外上游返回的实际美元账单换算结算。

Claude Opus 5.5 海外版

zhenzhen-op-5.5 映射到上游 anthropic/claude-opus-5.5，上下文最长 1,000,000 tokens，支持文本/图片输入、工具调用、推理、结构化输出和流式输出。参考价格（人民币每 1M tokens）：输入 ¥32.9412、输出 ¥164.7059、缓存读取 ¥3.2941、5 分钟缓存写入 ¥41.1765、1 小时缓存写入 ¥65.8824；最终按上游实际美元账单换算结算。租户别名遵循分隔符规则，例如 pickabc-op-5.5。

模型输入输出缓存读取缓存写入 5m缓存写入 1h
zhenzhen-op-5.5¥32.9412¥164.7059¥3.2941¥41.1765¥65.8824

TypeSafe Jev 1.13 结构化决策

typesafe/jev-1.13 使用同步 POST /v1/decisions（兼容 POST /api/alpha/decisions）。提交 state 和 questions，返回 answers 中的结构化选择及概率。上下文上限 32,000 tokens；不支持聊天、工具调用或流式输出。

curl https://api.seedance.nz/v1/decisions -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"model":"typesafe/jev-1.13","state":"A customer requests a refund.","questions":{"team":{"type":"choice","instructions":"Which team should handle this?","criteria":{"billing":"Payments and refunds","support":"Technical support"}}}}'

参考输入价 ¥0.3542 / 1M tokens，输出价 ¥0 / 1M tokens；最终按上游美元账单换算结算，具体以控制台为准。响应无需轮询。

GPT-6 Sol / Luna 节省版

zhenzhen/g6-sol、zhenzhen/g6-luna 支持文本与图片输入、工具调用、推理和流式输出，上下文最长 1,050,000 tokens。以下为人民币每 1M tokens 参考价，档位由完整输入上下文长度决定；最终按上游实际美元账单换算结算，以控制台定价为准。

模型≤272K：输入 / 输出 / 缓存读 / 缓存写>272K：输入 / 输出 / 缓存读 / 缓存写
zhenzhen/g6-sol¥5.7647 / ¥28.8235 / ¥0.5765 / ¥7.2059¥11.5294 / ¥43.2353 / ¥1.1529 / ¥14.4118
zhenzhen/g6-luna¥0.2882 / ¥1.4412 / ¥0.0288 / ¥0.3603¥0.5765 / ¥2.1618 / ¥0.0576 / ¥0.7206

GPT 节省版

zhenzhen/g5.6-sol、zhenzhen/g5.6-terra、zhenzhen/g5.6-luna、zhenzhen/g5.5 支持文本与图片输入、工具调用、推理和流式输出，上下文最长 1,050,000 tokens。以下为人民币每 1M tokens 参考价，档位由完整输入上下文长度决定；最终按上游实际美元账单换算结算，具体以控制台定价为准。

模型≤272K：输入 / 输出 / 缓存读 / 缓存写>272K：输入 / 输出 / 缓存读 / 缓存写
zhenzhen/g5.6-sol¥14.4118 / ¥86.4706 / ¥1.4412 / ¥18.0147¥28.8235 / ¥129.7059 / ¥2.8824 / ¥36.0294
zhenzhen/g5.6-terra¥5.7647 / ¥34.5882 / ¥0.5765 / ¥7.2059¥11.5294 / ¥51.8824 / ¥1.1529 / ¥14.4118
zhenzhen/g5.6-luna¥0.5765 / ¥3.4588 / ¥0.0576 / ¥0.7206¥1.1529 / ¥5.1882 / ¥0.1153 / ¥1.4412
zhenzhen/g5.5¥14.4118 / ¥86.4706 / ¥1.4412 / ¥18.0147¥28.8235 / ¥129.7059 / ¥2.8824 / ¥36.0294

GM 3.8 Flash

zhenzhen/gm-3.8-flash 支持文本与图片输入、工具调用、推理和流式输出，上下文上限为 1,048,576 tokens。输入 / 输出 / 缓存命中参考价分别为 ¥3.0882 / ¥15.4412 / ¥0.308824 每 1M tokens，按全上下文统一单价计费。最终按上游实际美元账单换算结算，具体以控制台为准。

请求

JSON Body
modelstring必填
deepseek/deepseek-v4.1-flash、deepseek/deepseek-v4-flash-vision-exp、glm/glm-5.3-flash、glm-5.3、qwen/qwen3.8-flash-next、qwen/qwen3.8-max、zhenzhen/gk-4.6、zhenzhen/g6-astra、zhenzhen/g6-sol、zhenzhen/g6-luna、zhenzhen/g5.6-sol、zhenzhen/g5.6-terra、zhenzhen/g5.6-luna、zhenzhen/g5.5、zhenzhen/gm-3.8-flash、zhenzhen-op-5.5 或 kimi-k3。模型名中的斜杠必须保留。
messagesarray必填
对话消息列表；每项含 role（system / user / assistant）与 content。
streamboolean可选
true 流式（SSE）；false 一次性返回。建议显式传值。
max_tokensinteger可选
最大生成 token 数（含推理消耗）。
temperaturenumber可选
采样温度，范围约 0–2。
终端
curl -X POST https://api.seedance.nz/v1/chat/completions \
 -H "Authorization: Bearer $SEEDANCE_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "model": "qwen/qwen3.8-max",
 "stream": false,
 "max_tokens": 256,
 "messages": [
 {"role": "user", "content": "用一句话介绍你自己"}
 ]
}'
响应 · json
{
 "id": "chatcmpl-...",
 "object": "chat.completion",
 "model": "kimi-k3",
 "choices": [
 {
 "index": 0,
 "message": {
 "role": "assistant",
 "content": "...",
 "reasoning_content": "..."
 },
 "finish_reason": "stop"
 }
 ],
 "usage": {
 "prompt_tokens": 20,
 "completion_tokens": 80,
 "total_tokens": 100
 }
}

语音转写（同步）

POST /v1/audio/transcriptions OpenAI Whisper 兼容语音转写，同步返回文本

模型：whisper-1。使用 multipart/form-data 上传音频，同步返回转写结果（无需轮询）。与异步 Seed Audio /v1/audio/generations 不是同一路径。

ℹ

计费按音频时长：1 分钟 = 1000 tokens。支持 mp3 / wav / flac / m4a / mp4 / ogg / opus / aac / aiff；当前不支持 webm。

请求

Form 参数 · multipart/form-data
filebinary必填
待转写的音频文件。
modelstring必填
whisper-1。
response_formatstring可选
json（默认）/ verbose_json / srt / text / vtt。
终端
curl -X POST https://api.seedance.nz/v1/audio/transcriptions \
 -H "Authorization: Bearer $SEEDANCE_API_KEY" \
 -F "file=@/path/to/audio.mp3" \
 -F "model=whisper-1" \
 -F "response_format=json"
响应 · json
{
 "text": "Hello world",
 "usage": { "type": "duration", "seconds": 10 }
}

提交音乐任务（Suno）

POST /v1/music/generations[/:action] 提交 Suno 音乐生成 / 二次处理任务（异步）
⚠

与 Seed Audio / Whisper 不是同一路径。 Seed Audio 用 /v1/audio/generations；语音转写用 /v1/audio/transcriptions； Suno 必须用 /v1/music/*。

ℹ

计费 SKU 由路径决定（如 suno-generation、suno-extend）， 不是请求体里的 model（上游固定为 suno）。 完整 action 表见 Suno 分类。

路径

路径计费 SKU说明
POST /v1/music/generationssuno-generation文生曲（灵感 / 自定义歌词）
POST /v1/music/generations/{action}suno-{action}action 为 kebab-case，见模型表

常用请求字段（generation）

JSON Body
versionstring必填
v3.5 / v4 / v4.5 / v4.5+ / v4.5-all / v5 / v5.5。影响音质与计费。
promptstring必填
灵感文案（custom=false）或歌词（custom=true）。
customboolean可选
false（默认）灵感模式；true 自定义歌词模式。
instrumentalboolean可选
true = 纯伴奏（无人声）。
title / style / vocal_genderstring可选
曲名、风格标签（字段名是 style 不是 tags）、人声偏好 Male/Female。
modelstring可选
可写 suno；网关路由不依赖此字段。

二次处理常见字段

  • task_id + 可选 audio_index（1-based，默认 1）：引用本站先前音乐任务的某一轨
  • task_ids（恰好 2 个）：仅 mashup
  • audioFilePath / audio_url / audio_urls：公网音频 URL（upload / create-voice / inspo）
  • 时间类：continue_at、start_s、end_s、duration_s、speed 等按 action 必填

本地校验失败（缺必填）返回 400，零扣费。

文生曲 · generation
curl -X POST https://api.seedance.nz/v1/music/generations \
 -H "Authorization: Bearer $SEEDANCE_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "model": "suno",
 "custom": false,
 "version": "v5",
 "prompt": "lo-fi piano with soft rain ambience",
 "instrumental": true
 }'
续写 · extend
curl -X POST https://api.seedance.nz/v1/music/generations/extend \
 -H "Authorization: Bearer $SEEDANCE_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "model": "suno",
 "task_id": "task_xxxxxxxxxxxx",
 "audio_index": 1,
 "continue_at": 30,
 "version": "v5.5"
 }'

响应

响应 · 200
{
 "code": 200,
 "data": [
 { "status": "submitted", "task_id": "task_xxxxxxxxxxxx" }
 ]
}

记下 data[0].task_id，用下方查询接口轮询。个别 action（如 upsample-tags）可能同步返回结果，仍可用同一查询接口。

查询音乐任务（Suno）

GET /v1/music/tasks/{task_id} 查询 Suno 任务状态与结果（透传上游形状，保留 music[]）

建议每 3~5 秒轮询，直到 data.status 为 completed / failed（或等价终态）。成功时从 data.result.music[] 取音轨（常见 2 首）。

终端
curl https://api.seedance.nz/v1/music/tasks/task_xxxxxxxxxxxx \
 -H "Authorization: Bearer $SEEDANCE_API_KEY"
响应 · completed（节选）
{
 "code": 200,
 "data": {
 "id": "task_xxxxxxxxxxxx",
 "task_id": "task_xxxxxxxxxxxx",
 "status": "completed",
 "progress": 100,
 "cost": 0.05,
 "result": {
 "music": [
 {
 "audio_id": "...",
 "audio_url": "https://.../track-a.mp3",
 "image_url": "https://.../cover.jpg",
 "title": "Probe Loop",
 "lyrics": "[Instrumental]",
 "duration": 103.56,
 "status": "complete"
 },
 {
 "audio_id": "...",
 "audio_url": "https://.../track-b.mp3",
 "duration": 86,
 "status": "complete"
 }
 ]
 }
 }
}
⚠

结果直链可能较短有效期，请尽快下载转存。二次处理请用本站返回的公开 task_* id（网关会映射到上游）。

提交 Midjourney 任务

POST /v1/midjourney/generations[/:action] 提交 Midjourney 文生图 / 二次操作 / 图生视频（异步）
⚠

与历史 /mj/* Discord 代理协议不是同一套。 本站接口：/v1/midjourney/*。计费 SKU 由路径决定（如 midjourney-imagine）， body.model 固定/可写 midjourney，不参与路由。完整 action 见 Midjourney。

路径

路径计费 SKU说明
POST /v1/midjourney/generationsmidjourney-imagine文生图 / 垫图（默认入口）
POST …/generations/imaginemidjourney-imagine显式 Imagine，与上等价
POST …/generations/{action}midjourney-{action}kebab-case action

Imagine 常用字段

JSON Body
promptstring必填
提示词；可含原生 MJ 参数（如 --ar 16:9 --v 6.1）。
speedstring可选
relax（默认）/ fast / turbo。
size / version / image_urlsmixed可选
宽高比、版本、垫图 URL；也可写在 prompt 的 -- 参数里（body 优先）。

二次操作

多数接口需要本站公开 task_id（网关映射上游）；选图类另需 index（1–4）或 custom_id（来自查询返回的 buttons[].customId）。

Imagine · relax
curl -X POST https://api.seedance.nz/v1/midjourney/generations \
 -H "Authorization: Bearer $SEEDANCE_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "prompt": "a small red apple on a white table, simple studio photo",
 "size": "1:1",
 "version": "6.1",
 "speed": "relax"
 }'
Upscale · U1
curl -X POST https://api.seedance.nz/v1/midjourney/generations/upscale \
 -H "Authorization: Bearer $SEEDANCE_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"task_id":"task_xxxxxxxxxxxx","index":1}'

响应

响应 · 200
{
 "code": 200,
 "data": [
 { "status": "submitted", "task_id": "task_xxxxxxxxxxxx" }
 ]
}

查询 Midjourney 任务

GET /v1/midjourney/tasks/{task_id} 查询状态与结果（MJ 风格：四宫格 / 单图 / buttons）

建议 3~5 秒轮询，直到 status 为 SUCCESS / FAILURE（或 MODAL 需再调 /modal）。 成功时读 image_urls（4 张）与 grid_image_url；二次操作用 buttons[].customId 或 index。

终端
curl https://api.seedance.nz/v1/midjourney/tasks/task_xxxxxxxxxxxx \
 -H "Authorization: Bearer $SEEDANCE_API_KEY"
响应 · SUCCESS（节选）
{
 {
 "id": "task_xxxxxxxxxxxx",
 "status": "SUCCESS",
 "progress": "100%",
 "cost": 0.04504,
 "grid_image_url": "https://.../grid.png",
 "image_urls": ["https://.../0.png", "https://.../1.png", "https://.../2.png", "https://.../3.png"],
 "buttons": [
 { "customId": "MJ::JOB::upsample::1::...", "label": "U1" },
 { "customId": "MJ::JOB::variation::1::...", "label": "V1" }
 ]
 }
⚠

结果直链可能较短有效期，请尽快下载转存。

上传参考素材

POST /v1/files/upload 上传本地文件，换取 24 小时有效的公网直链

没有自己的对象存储 / 图床时，用这个接口把本地素材换成可填入请求体的 URL。上传本身免费。

请求

Form 参数 · multipart/form-data
filebinary必填
要上传的文件。支持图片 JPG / JPEG / PNG / WEBP、音频 MP3 / WAV / FLAC、视频 MP4 / AVI / MOV / MKV；单文件 ≤ 50MB（生成任务对素材另有大小限制，见 提交视频任务）。
终端
curl -X POST https://api.seedance.nz/v1/files/upload \
 -H "Authorization: Bearer $SEEDANCE_API_KEY" \
 -F "file=@/path/to/person.png"

响应

响应 · 200
{
 "url": "https://.../xxxx.png?q-sign-algorithm=...",
 "file_type": "image",
 "size": 3490,
 "expires_in": 86400
}

把返回的 url 直接填入 images 或 metadata.content 即可。

⚠

链接仅 24 小时有效（expires_in: 86400）。这不是图床 / 网盘服务，请在有效期内提交生成任务，不要用于长期存储或外链分发。

ℹ

频率限制：每个令牌每分钟最多 30 次、每天最多 10000 次，超限返回 429；计数由 bridge 内存滑动窗口维护，重启 bridge 后清零。

参考素材指南

所有图片 / 视频 / 音频参考素材都通过公网可直接下载的 URL 传入请求体。获得这样的 URL 有两种方式：

方式一：使用本站上传接口（推荐）

没有外链时，用 POST /v1/files/upload 把本地文件换成 24 小时有效的直链，免费且同样用 API Key 鉴权。

方式二：使用你自己的公网直链

素材已经在自己的对象存储（腾讯云 COS、阿里云 OSS、AWS S3 等）或稳定图床上时，直接填直链即可。要求：

  • 必须是 http(s):// 直链：浏览器打开或 curl 请求该 URL 能直接得到文件本身（Content-Type 为对应的图片 / 视频 / 音频类型）；
  • 不支持 base64 内嵌、本地文件路径、需要登录的链接、网盘分享页（百度网盘 / 阿里云盘等分享链接打开的是网页而不是文件，无法使用）；
  • URL 需要在任务整个执行期间（提交后 10~30 分钟内）保持可访问，带签名的临时 URL 请确保有效期足够。
✓

素材不符合要求时（URL 不可达、格式不支持、超过大小限制），任务会提交失败或生成失败，费用全额退还。

视频超分（Zhenzhen Upscaler）

独立能力分类：把已有视频提升到更高分辨率。对外模型名 zhenzhen-upscaler （上游 rhart-video/video-upscaler）。 走与视频生成相同的异步接口 POST /v1/videos（兼容路径 POST /v1/video/generations）， 但请求字段与文生/图生视频不同——必填输入视频，不需要文案提示词。

请求字段

字段类型必填说明
model string 是 固定为 zhenzhen-upscaler
metadata.content array 是 恰好 1 条 video_url：{ "type": "video_url", "video_url": { "url": "https://..." } }。MP4，最长约 10 分钟；可先用 上传接口换直链
metadata.resolution string 否 目标分辨率 → 上游 targetResolution：720p / 1080p / 2k / 4k。默认 1080p
prompt string 否 不参与上游提交；可填占位如 upscale
seconds string 否 不参与上游提交；计费时长由上游从输入视频读取

提交示例

POST /v1/videos
{
 "model": "zhenzhen-upscaler",
 "prompt": "upscale",
 "metadata": {
 "resolution": "1080p",
 "content": [
 { "type": "video_url", "video_url": { "url": "https://your-cdn.example.com/source.mp4" } }
 ]
 }
}

查询与结果

与普通视频任务相同：用 GET /v1/videos/{task_id} 轮询；成功后从结果中的视频直链下载转存。

计费（按输入视频时长 × 目标分辨率）

提交前通过 price-preview 全额预扣；成功后按 最终实扣金额 结算，多退少补。牌价（指导价 / fallback）：

目标分辨率单价（元 / 秒）
720p¥0.14
1080p¥0.21
2k¥0.35
4k¥0.56

最终以控制台实际扣减为准。与 Seedance 的「超分附加费」（生成后再升分辨率）不是同一套计费。

模型列表

视频模型（Seedance 2.0，共 18 个）

模型名由三段组成，2 个区域 × 3 个档位 × 3 种任务类型：

seedance-2.0-[global-]{tier}-{task}
片段取值说明
[global-] 省略 / global- 省略为国内版（人民币结算）；带 global- 为国际版（美元结算后按汇率换算）。差异在上游站点与计费币种
{tier} standard / fast / mini Standard 质量最高（独占 native1080p / native4k 分辨率）；Fast 出片更快；Mini 最便宜
{task} t2v / i2v / multi 文生视频 / 图生视频 / 多模态视频
档位文生视频 t2v图生视频 i2v多模态 multi
Standard 国内 seedance-2.0-standard-t2v seedance-2.0-standard-i2v seedance-2.0-standard-multi
Fast 国内 seedance-2.0-fast-t2v seedance-2.0-fast-i2v seedance-2.0-fast-multi
Mini 国内 seedance-2.0-mini-t2v seedance-2.0-mini-i2v seedance-2.0-mini-multi
Standard 国际 seedance-2.0-global-standard-t2v seedance-2.0-global-standard-i2v seedance-2.0-global-standard-multi
Fast 国际 seedance-2.0-global-fast-t2v seedance-2.0-global-fast-i2v seedance-2.0-global-fast-multi
Mini 国际 seedance-2.0-global-mini-t2v seedance-2.0-global-mini-i2v seedance-2.0-global-mini-multi

所有 Seedance 2.0 视频模型均支持 seed 参数和 seconds: "-1"（自动时长）。接口见 提交视频任务。

视频模型（Seedance 2.5 Standard Token，共 6 个）

仅 Standard 档。国内 seedance-2.5-standard-*；海外 seedance-2.5-global-standard-*。分辨率 480p/720p/1080p/2k/4k/native1080p（无 native4k）；时长 4–30s 或 metadata.duration=-1。多模态最多 50 个参考：30 图 + 10 视频 + 10 音频（单段音视频 2–30s，总长 ≤30s）。

区域文生 t2v图生 i2v多模态 multi
国内 (.cn) seedance-2.5-standard-t2v seedance-2.5-standard-i2v seedance-2.5-standard-multi
海外 (.ai) seedance-2.5-global-standard-t2v seedance-2.5-global-standard-i2v seedance-2.5-global-standard-multi

视频模型（HappyHorse 1.1，共 3 个）

模型名类型说明
happyhorse-1.1-t2v 文生视频 prompt 必填；resolution=720p/1080p；seconds=3~15；可选 metadata.ratio（aspectRatio）
happyhorse-1.1-i2v 图生视频 需 images（取首图）；prompt 可选；不支持 seconds=-1
happyhorse-1.1-r2v 参考图生视频 prompt 必填（可用「图1/图2」）；images 1~9 张 → 上游 imageUrls；可选 metadata.ratio

按秒牌价：720p ¥0.69/s，1080p ¥0.92/s。接口同 提交视频任务。

图片模型（Seedream V5 Pro / V5 Flash 共 12 个，另有 Zhenzhen Image G-2）

模型名类型说明
seedream-v5-pro-t2i 文生图（国内） 仅需 prompt；可选 resolution（1k/2k）或 width/height
seedream-v5-pro-i2i 图生图（国内） prompt + images[]（1~10 张参考图）
seedream-v5-pro-layer-decomposition 图层拆分（国内） 恰好 1 张 images[]；prompt 可选；返回 1 张底图 + 最多 16 个 PNG 图层
dola-seedream-5.0-pro-t2i 文生图（海外） 字段同国内 t2i；海外版
dola-seedream-5.0-pro-i2i 图生图（海外） 字段同国内 i2i；海外版
dola-seedream-5.0-pro-layer-decomposition 图层拆分（海外） 恰好 1 张 images[]；返回底图与有序图层 URL；实测无 z_index / bounding_box
seedream-v5-flash-t2i V5 Flash 文生图（国内） prompt 5 ~ 5000；resolution 1k/1.5k/2k 或宽高各 240 ~ 8192
seedream-v5-flash-i2i V5 Flash 图生图（国内） images[] 1 ~ 10 张、单张 ≤30MB；prompt 5 ~ 5000
seedream-v5-flash-layer-decomposition V5 Flash 图层拆分（国内） 恰好 1 张 ≤30MB 输入图；底图 jpeg/png、图层 PNG；返回图片 URL 列表
dola-seedream-5.0-flash-t2i V5 Flash 文生图（海外） 参数同国内 Flash t2i；上游 dola-Seedream-5.0-flash/text-to-image
dola-seedream-5.0-flash-i2i V5 Flash 图生图（海外） 参数同国内 Flash i2i；上游 dola-Seedream-5.0-flash/image-to-image
dola-seedream-5.0-flash-layer-decomposition V5 Flash 图层拆分（海外） 单图输入；prompt 可选、≤2000；图片 URL 列表，无额外图层元数据保证
zhenzhen-image-g2-t2i 文生图（Zhenzhen Image G-2） resolution 仅 1k；可选 metadata.ratio→aspectRatio；不支持 2k / output_format
zhenzhen-image-g2-i2i 图生图（Zhenzhen Image G-2） prompt + images[]；resolution 仅 1k；可选 metadata.ratio

接口见 提交图片任务。

图片模型（Qwen-Image 3.0 / 3.0-Pro，共 8 个）

模型名类型说明
qwen-image-3.0-t2i 文生图（国内） 可选 n、size 或 ratio+resolution(1k/2k)；省略 size 自动推荐
qwen-image-3.0-i2i 图像编辑（国内） images[] 1–3；image-edit
qwen-image-3.0-pro-t2i / qwen-image-3.0-pro-i2i Pro 文生图 / 编辑（国内） 参数同上；Pro 牌价更高
qwen-image-3.0-global-* / qwen-image-3.0-global-pro-* 海外版 使用海外版；USD 结算后按 结算汇率 换算

接口见 提交图片任务。

Wan 2.7 Spicy（图生视频，1 个）

模型名类型说明
wan-2.7-spicy-i2v 图生视频 images[0] 必填；seconds 2–15；resolution 720p/1080p；可选 prompt / audio_url / negative_prompt / prompt_extend / seed

按秒牌价：720p ¥0.91/s，1080p ¥1.4/s。接口同 提交视频任务。

Wan 3.0（视频，标准版与 Prime 高速版，国内与海外共 12 个）

模型名类型说明
wan-3.0-i2v图生视频首帧必填、尾帧可选；2–30 秒或 auto；480P/720P/1080P
wan-3.0-r2v参考生视频图片≤10、视频≤5、音频≤5；可选互斥的 file_url/link_url
wan-3.0-global-i2v海外图生视频美元计价；首帧必填、尾帧可选
wan-3.0-global-r2v海外参考生视频美元计价；file_url/link_url 自动开启深度思考
wan-3.0-prime-i2vPrime 国内图生视频高速版；首帧必填、尾帧可选；2–30 秒或 auto
wan-3.0-prime-r2vPrime 国内参考生视频高速版；图片≤10、视频≤5、音频≤5；可选 file_url/link_url
wan-3.0-global-prime-i2vPrime 海外图生视频美元计价
wan-3.0-global-prime-r2vPrime 海外参考生视频美元计价
wan-3.0-t2v国内文生视频必填 prompt，无参考素材；默认 720P
wan-3.0-prime-t2vPrime 国内文生视频高速版；默认 1080P
wan-3.0-global-t2v海外文生视频默认 720P；美元计价
wan-3.0-global-prime-t2vPrime 海外文生视频高速版；默认 1080P；美元计价

比例支持 adaptive/16:9/4:3/1:1/3:4/9:16；音频默认开启；seed 0–2147483647。终态按最终实扣金额结算，成功结果为单个 MP4 URL。具体价格以控制台为准。

文生视频使用 POST /v1/video/generations，以 GET /v1/video/generations/{id} 轮询。必填 prompt（≤20000 字符），不传参考素材。seconds 为 2–30（默认 5）；自动时长请省略 seconds 并传 metadata.duration=-1。metadata.resolution 可选 480P/720P/1080P，metadata.ratio 默认 adaptive；metadata.generate_audio=false 关闭音轨，可选 metadata.seed 支持显式 0。

媒体模型（共 68 个，按次计费）

ℹ

这三家均为按次计费（按最终实扣金额结算），不是 Seedance 的 Token 按量。提交前 price-preview 预扣，成功后按实际金额结算，失败全额退款。接口同 提交视频任务。

Wan 2.7 海外图片（3 个）

模型名类型说明
wan-2.7-global-t2i文生图prompt ≤5000；可选 width/height 512–4096、thinking_mode
wan-2.7-global-i2i图像编辑images[] 1–9；prompt ≤2048
wan-2.7-global-i2i-pro图像编辑 Proimages[] 1–9；最高 2K；prompt ≤2048

使用 /v1/image/generations 提交；海外版最终费用按人民币结算，具体金额以控制台为准。

可灵 Kling（28）

模型名类型
kling-v3.0-std-t2v / kling-v3.0-pro-t2v文生视频 v3.0
kling-v3.0-std-i2v / kling-v3.0-pro-i2v图生视频 v3.0（首帧，可选尾帧）
kling-v3-turbo-std-t2v / kling-v3-turbo-pro-t2v文生视频 v3 turbo
kling-v3-turbo-std-i2v / kling-v3-turbo-pro-i2v图生视频 v3 turbo
kling-v3-4k-t2v / kling-v3-4k-i2v文生 / 图生 4K
kling-o3-std-t2v / kling-o3-pro-t2v文生视频 o3
kling-o3-std-i2v / kling-o3-pro-i2v图生视频 o3
kling-o3-std-r2v / kling-o3-pro-r2v参考生视频 o3
kling-o3-std-edit / kling-o3-pro-edit视频编辑（需 video_url）
kling-o3-4k-t2v / kling-o3-4k-i2v / kling-o3-4k-r2vo3 4K
kling-v3.0-std-motion / kling-v3.0-pro-motion / kling-v3.0-4k-motion动作控制（图+视频）
kling-elements-advancedo3 多主体
kling-lip-sync-identify-face / kling-lip-sync-tts / kling-lip-sync-video对口型多步套件

海螺 Hailuo 2.3（6）

模型名类型
hailuo-2.3-t2v-standard / hailuo-2.3-t2v-pro文生视频
hailuo-2.3-i2v-standard / hailuo-2.3-i2v-pro图生视频
hailuo-2.3-fast-i2v / hailuo-2.3-fast-pro-i2v图生视频 fast

海螺 Hailuo H3（6，国内 + 海外）

模型名类型
hailuo-h3-t2v / hailuo-h3-global-t2v文生视频（768P/2K，时长 5–15s，可选 ratio）
hailuo-h3-i2v / hailuo-h3-global-i2v图生视频（首帧必填，可选尾帧）
hailuo-h3-multi / hailuo-h3-global-multi多模态参考生视频（图≤9 / 视频≤3 / 音频≤3）

global 变体走 海外版，并按美元成本换算人民币结算。

MiniMax H3 Max（2，国内版）

模型名类型与参数
hailuo-h3-max-t2v文生视频；prompt 必填；480P/768P；5–15 秒；六种 ratio 必填
hailuo-h3-max-i2v首尾帧图生视频；images 1–2 张依次映射首帧/尾帧；480P/768P；5–15 秒

牌价为 480P ¥0.41/秒、768P ¥0.63/秒；任务完成后按最终实扣金额结算。

MiniMax H3 Max Turbo（2，国内版）

模型名类型与参数
hailuo-h3-max-turbo-t2v文生视频；prompt 必填；小写 480p/768p；5–15 秒；六种 ratio 必填并映射 aspectRatio
hailuo-h3-max-turbo-i2v首尾帧图生视频；images 1–2 张依次映射必填首帧/可选尾帧；小写 480p/768p；5–15 秒；不接受 ratio

牌价为 480p ¥0.175/秒、768p ¥0.28/秒；任务完成后按最终实扣金额结算。prompt 最多 20480 字符。

MiniMax H3 Context IR（3，返回增强提示词）

这三个模型只增强视频提示词，不生成视频。提交 POST /v1/video/generations，轮询 GET /v1/video/generations/{id}；成功响应的增强提示词位于 result_text。

模型名参数
minmax-h3-context-ir-textprompt 1–7000 字符；seconds 4–15；metadata.ratio 必填
minmax-h3-context-ir-image另需 images 1–2 张，映射首帧/尾帧
minmax-h3-context-ir-multimodal图≤9 / 视频≤3 / 音频≤3；比例可选并支持 adaptive

三个模型均按最终实扣金额结算。

FLUX 3 Video（8，国内 + 海外）

模型名类型
flux-3-video-t2v / flux-3-video-global-t2v文生视频
flux-3-video-i2v / flux-3-video-global-i2v图生视频（1–10 张关键帧）
flux-3-video-v2v / flux-3-video-global-v2v视频续生（需 metadata.video_url）
flux-3-video-draft-enhance / flux-3-video-global-draft-enhance草稿增强（需上一草稿任务返回的 metadata.draft_cache）

生成参数：5–20s，hd/fhd，8 种比例；可选草稿、同步音频与 0–4 审核容忍度。global 变体使用海外版。

qwen image global 2.1

使用海外应用，提供 1K、2K、4K 分辨率，默认 2K，最高 4K。

qwen-image-global-2.1 同时支持文生图和图生图：不传 images 时按提示词生成，传入 1–10 张参考图时按图生成。统一使用 POST /v1/image/generations，1K 为 ¥0.10、2K 为 ¥0.20/张，4K 为 ¥0.40/张。支持 8 种画面比例和可选种子，默认 3:4。使用 metadata.resolution 选择分辨率，长边最高 4096 像素。完整参数与请求示例

Animate Motion Transfer（Animate 动作迁移）

animate-motion-transfer 将参考视频动作迁移到一张角色图片。使用 POST /v1/video/generations 提交及 GET /v1/video/generations/{id} 查询；必填一张 images 和一条 metadata.video_url。支持 480P / 720P / 1080P，固定零售价分别为 ¥0.20 / ¥0.30 / ¥0.40 每生成秒，按实际输出时长结算（含小数秒）。1080P 最多 10 秒，不支持 ZIP。完整参数与请求示例

Minimax H3 OW / FlashVSR / VOSR2（视频与超分，11）

模型名类型
minimax-h3-ow-t2v全能视频（480P/768P/1080P；时长 5/10/15s；最多 9 图 + 3 音频 + 3 视频任意组合）
minimax-h3-ow-r2v全能参考视频（同上参数/定价；最多 9 图 + 3 音频 + 3 视频任意组合）
minimax-h3-ow-i2v全能视频（同上参数/定价；最多 9 图 + 3 音频 + 3 视频任意组合）
minimax-h3-ow-r2v-fast全能极速参考视频（独立定价；最多 9 图 + 3 音频 + 1 视频任意组合；含视频时同档价格 ×1.5）
minimax-h3-ow-i2v-fast全能极速视频（独立定价；最多 9 图 + 3 音频 + 3 视频任意组合）
minimax-h3-ow-fl2va-audio-drive-fast极速音频驱动视频（必填且仅支持 1 张人物图与 1 条音频 URL）
minimax-h3-ow-ref2va-audio-drive-fast极速参考音频驱动视频（必填且仅支持 1 张参考图与 1 条音频 URL）
minimax-h3-ow-t2v-fast全能极速视频（独立定价；最多 9 图 + 3 音频 + 3 视频任意组合）
FlashVSR_video_upscaleMiniMax H3 480P→1080P 视频放大；输入 480P、3–15 秒；仅一个 metadata.video_url；固定 ¥1/次
vosr2-video-upscaleVOSR2 视频高清化；仅一个 metadata.video_url；输出 2K；按最终实扣金额结算
vosr2-image-upscaleVOSR2 图像高清化；仅一张 images；输出 4K；按最终实扣金额结算

六个全能 t2v / i2v / r2v 及对应 fast SKU 支持 480P / 768P / 1080P，时长 5/10/15 秒。普通版价格：480P 为 ¥0.2/¥0.5/¥1，768P 为 ¥0.5/¥1/¥2，1080P 为 ¥0.6/¥1.5/¥3；fast 版价格：480P 为 ¥0.3/¥0.5/¥1，768P 为 ¥0.6/¥1/¥2，1080P 为 ¥0.9/¥1.5/¥3。r2v-fast 包含参考视频时同档价格 ×1.5。

最多 9 图、3 音频；r2v-fast 最多 1 视频，其余最多 3 视频；媒体均可选，参考视频不超过 15 秒。两个 audio-drive SKU 使用 480p/720p 档位，必填 1 张图和 1 条音频。

Vidu Q3（15）

模型名类型
vidu-q3-pro-t2v / vidu-q3-turbo-t2v / vidu-q3-pro-fast-t2v文生视频
vidu-q3-pro-i2v / vidu-q3-turbo-i2v / vidu-q3-pro-fast-i2v图生视频
vidu-q3-pro-start-end / vidu-q3-turbo-start-end / vidu-q3-pro-fast-start-end首尾帧
vidu-q3-r2v / vidu-q3-mix-r2v / vidu-q3-ad-r2v / vidu-q3-drama-r2v参考生视频
vidu-q3-drama-short-play / vidu-q3-ad-short-play短剧成片

字段细节与特殊参数见 Markdown 文档 llms.txt 对应章节。

Vidu Q4 Preview（4）

模型名类型
vidu-q4-preview-r2v / vidu-q4-preview-global-r2v参考生视频，1–15 张图，最多 3 段 MP3
vidu-q4-preview-i2v / vidu-q4-preview-global-i2v图生视频，1 张首帧

时长 3–16 秒，分辨率 540p / 720p / 1080p / 2k / 4k。参考生视频可选画幅 16:9、9:16、1:1、4:3、3:4。带 global 的名称走海外接口，按美元成本折成人民币结算。

Image G v2.5：Flare / Sunburst

zhenzhen-image-g-v2.5-flare 官方版。支持文生图与参考图编辑，适合日常创作与快速迭代。zhenzhen-image-g-v2.5-sunburst 官方版。支持文生图与参考图编辑，侧重精细编辑。

提交 POST /v1/image/generations，通过 GET /v1/image/generations/{id} 查询结果。添加 images 即进入编辑模式；省略 size 可保留参考图比例。按实际消耗结算，失败全额退款，金额以控制台为准。

参数取值与说明
model / prompt必填；使用上述完整模型名和生成或编辑描述。
images可选，最多 16 张公开 HTTP(S) 图片地址。
n整数 1–4，默认 1。
size可省略，或 auto / 1:1 / 3:2 / 2:3 / 4:3 / 3:4 / 5:4 / 4:5 / 16:9 / 9:16 / 2:1 / 1:2 / 21:9 / 9:21 / 3:1 / 1:3，也支持 1600x1200 等像素尺寸。宽高须为 16 的倍数且均不超过 3840，最长边与最短边之比不超过 3:1，总像素为 655360–8294400。
resolution1k / 2k / 4k，默认 1k；指定精确像素尺寸时忽略。
qualityauto / low / medium / high / xhigh / max。默认 auto；示例使用 low。auto 在生成时选择质量，最终按实际消耗结算。
output_formatpng / jpeg / webp，默认 png。
output_compression可选整数 0–100，仅 jpeg / webp 可用，png 请省略。
backgroundauto / transparent / opaque；透明背景仅支持 png / webp。
moderationlow / auto，默认 low。
文生图示例
curl https://api.seedance.nz/v1/image/generations \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"zhenzhen-image-g-v2.5-flare","prompt":"A red ceramic teapot on a white table","resolution":"1k","quality":"low","n":1}'

编辑时改用所需模型并添加 "images":["https://example.com/reference.png"]。返回任务 ID 后轮询至成功，及时保存结果图片。暂不支持流式图片。

Image G v2.5：低价扩展版

低价扩展版，支持文生图和参考图编辑，提供 1k / 2k / 4k 输出。上游正在灰度升级，实际模型版本随账号升级进度而定。

提交 POST /v1/image/generations，通过 GET /v1/image/generations/{id} 查询结果。按实际消耗结算，失败全额退款，金额以控制台为准。

参数取值与说明
model必填：zhenzhen-image-g-v2.5-lowprice。
prompt必填，1–5000 字符，描述生成或编辑需求。
images可选，最多 15 张公开 HTTP(S) 图片地址，按输入顺序参与编辑。
n仅支持 1，每次返回一张图片。
sizeauto / 1:1 / 1:3 / 3:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 5:4 / 4:5 / 2:1 / 1:2 / 21:9 / 9:21；默认 16:9，auto 根据提示词或参考图决定比例。
resolution1k / 2k / 4k，默认 1k。
nsfw_check布尔值 true / false，默认 false，控制生成前的内容安全检查。
文生图示例
curl https://api.seedance.nz/v1/image/generations \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"zhenzhen-image-g-v2.5-lowprice","prompt":"A red ceramic teapot on a white table","resolution":"1k","size":"16:9","n":1,"nsfw_check":false}'

编辑时添加 "images":["https://example.com/reference.png"]，可使用 "size":"auto"。结果图片直链约 24 小时过期，请及时保存。此扩展版不提供质量档位、输出格式、透明背景或流式选项。

Zhenzhen 扩展视频 / 图片

ℹ

视频走 /v1/videos，图片走 /v1/image/generations。 按实际消耗结算：提交预扣、成功多退少补、失败全额退款。结果直链约 24 小时过期。 注意：zhenzhen-image-g-v2-lowprice 与 zhenzhen-image-g2-* 是不同模型。

视频（6）

模型名说明
zhenzhen-video-gk-v15 文生/图生视频。seconds 6–30（默认 6）；resolution 480p/720p；metadata.ratio 16:9/9:16/1:1/3:2/2:3；可选 images≤7
zhenzhen-video-v31-fast 视频（fast）。时长固定 8s；resolution 720p/1080p/4k；ratio 16:9/9:16；images≤3（1=首帧，2=首尾帧，3=reference）；可选 metadata.type=frame/reference
zhenzhen-video-v31-quality 视频（quality）。同 fast，但禁止 reference（勿传 type=reference 或 3 张参考图）
zhenzhen-video-v31-lite 视频（lite）。仅文生视频；勿传 images / metadata.type；时长固定 8s；resolution 720p/1080p/4k；ratio 16:9/9:16
zhenzhen-video-g-omni-flash 多模态视频（文/图/视频编辑）。prompt 和/或 images≤16 / metadata.video_url（≤1）/ metadata.extend_from_task_id（与 video_url 互斥）；resolution 仅 720p；时长不可指定
zhenzhen-video-g-omni-flash-lowprice 文生、图生与参考视频生成。prompt 必填；seconds 为 4/6/8/10（默认 6）；resolution 为 720p/1080p/4k；aspect_ratio 为 16:9/9:16；images 支持 0/1/3 张；参考视频使用 metadata.video_url（≤1）并省略时长
zhenzhen-video-g-omni-1.1-flash-lowprice 文生、图生与参考视频生成。prompt 必填；seconds 为 4/6/8/10（默认 6）；resolution 为 720p/1080p/4k；aspect_ratio 为 16:9/9:16；images 支持 0/1/3 张；参考视频使用 metadata.video_url（≤1）并省略时长

图片

模型名说明
zhenzhen-image-g-v2.5-lowprice低价扩展版，1k / 2k / 4k，最多 15 张参考图、单张输出；上游灰度升级中。参数与示例
zhenzhen-image-g-v2.5-flare文生图与参考图编辑，最多 16 张参考图，1k / 2k / 4k，自定义尺寸，1–4 张输出。参数与示例
zhenzhen-image-g-v2.5-sunburst文生图与精细参考图编辑，参数同 Flare。参数与示例
zhenzhen-image-g-v2-lowprice 文生图/图生图。resolution 1k/2k/4k；顶层 n 1–10；size（或 metadata.ratio）比例枚举或 WxH；可选 images≤16
zhenzhen-image-gk-v15 文生图。n 1–10；size 1:1/16:9/9:16/3:2/2:3
zhenzhen-image-gk-v15-edit 图编辑。必填 images[]（取首张）；n 1–10
zhenzhen-image-gk-v2 Grok Imagine 2.0 仅文生图，不接受 images。n 1–12；size 1:1/2:3/3:2/3:4/4:3/9:16/16:9；resolution 可省略或为 quality
zhenzhen-image-gk-v2-edit 图编辑/多图参考。必填 images 1–3 张；n 1–10；aspect_ratio 为 auto 或 13 种固定比例；resolution 为 1k/2k；可选 nsfw_check；不接受 quality
zhenzhen-image-gk-v2-segment 对象分割。operation=segment；必填 source_task_id；免费；完成结果位于 data.content.result
zhenzhen-image-gk-v2-region-edit 区域编辑。operation=region_edit；必填 image_id、prompt；选区可使用多边形、边界框或对象索引
zhenzhen-image-nb-flash Nano Banana。文生图/图生图；resolution 仅 1k；n=1；size 含 auto/21:9；可选 images≤14；prompt≤1000
zhenzhen-image-nb-2 Nano Banana 2。文生图/图生图；resolution 0.5k/1k/2k/4k；n=1；含极端比例 1:8/8:1；可选 images≤14；不支持 output_format（含 metadata.output_format），传入返回 400；输出图片格式由上游决定
zhenzhen-image-nb-2.1 Nano Banana 2.1。文生图/图生图；resolution 1k/2k/4k；n=1；可选 images≤14；参数与调用示例
zhenzhen-image-nb-2-lite Nano Banana Lite。文生图/图生图；resolution 仅 1k；n 1–4；可选 images≤14
zhenzhen-image-nb-pro Nano Banana Pro。文生图/图生图；resolution 1k/2k/4k；n=1；可选 images≤14
flux-3-imageFLUX 3 Image: text-to-image and reference editing; up to 10 references; aspect_ratio supports 15 ratios and auto; resolution is 768sq/1k/1.5k/2k/4k; n=1; supports grounding and safety_tolerance

字段细节与 curl 示例见 llms.txt「Zhenzhen 扩展」章节。

视频超分（Zhenzhen Upscaler，1 个）

独立分类，详见 视频超分。模型：zhenzhen-upscaler。

Midjourney

ℹ

完整接口文档见侧栏 Midjourney 树： 概览 · Imagine · 最佳实践 · 完整工作流 等。 计费：按实际上游消耗结算，失败全额退款；轮询 GET /v1/midjourney/tasks/{id}。

Suno 音乐

ℹ

完整接口文档见侧栏 Suno 树： 概览 · Generate music 等全部分页。 计费：按实际上游消耗结算（部分工具按次），失败全额退款；轮询 GET /v1/music/tasks/{id}。

音频模型（Doubao Seed Audio 1.0，共 1 个）

模型名类型说明
doubao-seed-audio-1.0 音频生成 POST /v1/audio/generations；prompt 必填；可选 metadata.speaker / 参考音频 / images（互斥）
mureka-v8-bgm / mureka-v9-bgm 伴奏生成 POST /v1/audio/generations；prompt / metadata.instrumental_id 二选一；metadata.n 1–3；¥0.34/条

Seed Audio 牌价约 ¥0.004/秒；Mureka 牌价 ¥0.34/条。接口见 提交音频任务。

Flow Music

ℹ

完整接口文档见侧栏 Flow Music 树： 生成音乐 · 生成歌词 · 续写 · 任务查询 等全部分项。 请求体使用 model=flowmusic，可选版本 lyria-3.5； 成功任务按实际上游消耗结算，失败全额退款；轮询 GET /v1/music/tasks/{id}。

文本对话（DeepSeek / Qwen / GLM / GK / GPT / GM / Kimi，共 17 个）

模型名类型说明
deepseek/deepseek-v4.1-flash 多模态对话 POST /v1/chat/completions（同步/流式）；国内版；262,144 tokens 上下文；支持图片输入、工具调用、推理、上下文缓存和结构化输出
deepseek/deepseek-v4-flash-vision-exp 多模态对话 POST /v1/chat/completions（同步/流式）；国内版实验版；1,048,576 tokens 上下文；支持图片输入、工具调用和结构化输出
glm/glm-5.3-flash 文本对话 POST /v1/chat/completions（同步/流式）；国内版；262,144 tokens 上下文
glm-5.3 文本对话 POST /v1/chat/completions（同步/流式）；国内版；1,048,576 tokens 上下文；纯文本、始终推理
qwen/qwen3.8-flash-next 文本对话 POST /v1/chat/completions（同步/流式）；国内版；262,144 tokens 上下文
qwen/qwen3.8-max 文本对话 POST /v1/chat/completions（同步/流式）；OpenAI 兼容；1M 上下文；支持工具调用、推理、Web Search 与结构化输出
zhenzhen/gk-4.6 文本对话 POST /v1/chat/completions（同步/流式）；OpenAI 兼容；500K 上下文；支持视觉、工具调用与推理；200K tokens 起进入长上下文价格档
zhenzhen/g6-astra 多模态对话 POST /v1/chat/completions（同步/流式）；OpenAI 兼容；1,050,000 tokens 上下文；支持视觉、工具调用与推理；272K tokens 后进入长上下文价格档
zhenzhen-op-5.5多模态对话POST /v1/chat/completions（同步/流式）；1,000,000 tokens 上下文；支持视觉、工具调用、推理与结构化输出；按上游美元账单换算结算
zhenzhen/g6-sol多模态对话POST /v1/chat/completions（同步/流式）；1,050,000 tokens 上下文；支持视觉、工具调用与推理；272K tokens 后进入长上下文价格档
zhenzhen/g6-luna多模态对话POST /v1/chat/completions（同步/流式）；1,050,000 tokens 上下文；支持视觉、工具调用与推理；272K tokens 后进入长上下文价格档
zhenzhen/g5.6-sol多模态对话POST /v1/chat/completions（同步/流式）；1,050,000 tokens 上下文；支持视觉、工具调用与推理；272K tokens 后进入长上下文价格档
zhenzhen/g5.6-terra多模态对话POST /v1/chat/completions（同步/流式）；1,050,000 tokens 上下文；支持视觉、工具调用与推理；272K tokens 后进入长上下文价格档
zhenzhen/g5.6-luna多模态对话POST /v1/chat/completions（同步/流式）；1,050,000 tokens 上下文；支持视觉、工具调用与推理；272K tokens 后进入长上下文价格档
zhenzhen/g5.5多模态对话POST /v1/chat/completions（同步/流式）；1,050,000 tokens 上下文；支持视觉、工具调用与推理；272K tokens 后进入长上下文价格档
zhenzhen/gm-3.8-flash多模态对话POST /v1/chat/completions（同步/流式）；1,048,576 tokens 上下文；支持视觉、工具调用与推理；按输入/输出/缓存命中用量计费
kimi-k3 文本对话 POST /v1/chat/completions（同步/流式）；OpenAI 兼容；约 1M 上下文

接口见 文本对话。

语音转写（Whisper，共 1 个）

模型名类型说明
whisper-1 语音转写 POST /v1/audio/transcriptions（同步 multipart）；按时长计费，1 分钟 = 1000 tokens

接口见 语音转写。

Nano Banana 2.1

模型名：zhenzhen-image-nb-2.1。支持文生图与图生图，输出分辨率为 1k / 2k / 4k，每次生成 1 张图片。

字段说明
model必填，zhenzhen-image-nb-2.1。
prompt必填，5–5000 字符，描述生成或编辑需求。
images可选，最多 14 张参考图片的公开 HTTP(S) 地址。不传为文生图，传入为图生图。
n仅支持 1，默认 1。
sizeauto / 1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9 / 21:9；文生图默认 1:1。
metadata.resolution1k / 2k / 4k，默认 1k。

不支持 output_format（包括 metadata.output_format），请省略；图片格式由生成服务决定。按实际消耗结算，失败全额退款，金额以控制台为准。

文生图

cURL
curl -X POST https://api.seedance.nz/v1/image/generations \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zhenzhen-image-nb-2.1",
    "prompt": "A small ceramic teapot on a wooden table, soft studio light",
    "n": 1,
    "size": "1:1",
    "metadata": { "resolution": "1k" }
  }'

图生图

在同一请求中添加 images，可用 size=auto 自动选择比例：

JSON
{
  "model": "zhenzhen-image-nb-2.1",
  "prompt": "将茶壶改成蓝色，保留原有形状与桌面背景",
  "images": ["https://example.com/reference.png"],
  "n": 1,
  "size": "auto",
  "metadata": { "resolution": "2k" }
}

查询生成结果

提交后保存任务 ID，每 3–5 秒查询一次，直到 data.status 为 SUCCESS 或 FAILURE。成功图片直链位于 data.result_url，最终实扣金额位于 data.usage。

cURL
curl https://api.seedance.nz/v1/image/generations/TASK_ID \
  -H "Authorization: Bearer $SEEDANCE_API_KEY"

结果链接约 24 小时过期，请及时下载转存。图片提交与查询的通用结构见 提交图片任务和查询图片任务。

价格与计费

ℹ

可灵 / 海螺 / Vidu 为按次计费；Zhenzhen 扩展 / Suno / Midjourney 按上游消耗结算。下方 Token 公式仅适用于 Seedance 2.0 视频模型。

Seedance 按任务实际消耗的 Token 数计费，任务成功后结算；选择 1080p / 2k / 4k 超分档时，另按输出视频时长收取超分附加费：

计费公式
总费用 = Token 单价 × 实际消耗 Token 数 ÷ 1,000,000
 + 超分附加费单价 × 输出视频时长（秒） # 仅 1080p / 2k / 4k 档
ℹ

Token 消耗量由模型在任务完成后返回，与分辨率、时长、内容复杂度相关，提交前只能估算区间。建议先用低分辨率、短时长试跑，统计 Token 用量后再评估成本。最终计费以控制台余额扣减为准。

Token 单价（元 / 百万 Token）

多模态模型（-multi）传入参考视频（video_url）时，按「有参考视频」的低单价档计费；文生视频、图生视频均按「无参考视频」档计费。国内版与国际版价格相同。

档位分辨率无参考视频有参考视频
Standard480p / 720p¥46¥28
1080p / 2k / 4k / native1080p¥51¥31
native4k¥26¥16
Fast全部分辨率¥37¥22
Mini全部分辨率¥23¥14
ℹ

native4k 的 Token 单价最低，但 4K 原生输出单位时长消耗的 Token 数远高于低分辨率，总价并不低。native1080p / native4k 仅 Standard 档支持。

超分附加费（元 / 秒，按输出时长计）

分辨率附加费
480p / 720p / native1080p / native4k免费
1080p¥0.28
2k¥0.42
4k¥0.63

计费示例

假设一个 seedance-2.0-standard-t2v（无参考视频）任务，选择 1080p，生成了 5 秒视频，实际消耗 400,000 Token：

演算
Token 费用 = ¥51 × 400,000 ÷ 1,000,000 = ¥20.40
超分附加费 = ¥0.28 × 5 秒 = ¥ 1.40
─────────────────────────────────────────────
总费用 = ¥21.80 （示例中的 Token 数仅为演示，实际以任务返回为准）
✓

多退少补，失败退款。提交任务时预扣的额度仅为占位，任务成功后按实际用量结算并自动退还差额；提交失败、生成失败均全额退款。

图片计费（Seedream）

图片任务按上游实际消费金额结算（提交前通过价格预估全额预扣，成功后多退少补）：

计费公式
总费用 = 最终实扣金额（人民币）
参考场景（实测）约合费用
seedream-v5-pro-t2i · resolution=2k≈ ¥0.54 / 张
seedream-v5-pro-i2i · resolution=1k≈ ¥0.27 / 张
seedream-v5-pro-layer-decomposition≤236 万像素 ¥0.27/张；更高 ¥0.54/张
dola-seedream-5.0-pro-layer-decomposition≤236 万像素 $0.041/张；更高 $0.081/张（USD→CNY）
seedream-v5-flash-*（t2i/i2i/图层拆分）官方 ¥0.11 / 实际输出图
dola-seedream-5.0-flash-*（t2i/i2i/图层拆分）官方 $0.016 / 实际输出图（USD→CNY）

V5 Flash 图层拆分按实际输出张数计算。表中 Flash 价格为上游参考牌价，最终按终态实际消耗、站点折扣与控制台扣费为准；海外美元成本先换算成人民币。V5 Pro 的分辨率、宽高、内容复杂度会影响价格。

Zhenzhen 扩展模型计费

按实际消耗结算（人民币）：提交预扣 → 成功多退少补 → 失败全额退款。结果 URL 约 24 小时过期。最终以控制台余额扣减为准。

Midjourney 计费（按上游 cost USD）

计费公式
按任务完成后的实际上游消耗结算为人民币；提交预扣，成功多退少补，失败全额退款。具体金额以控制台预估与余额变动为准。

实测参考：midjourney-imagine @ v6.1 relax 单次 cost≈0.045 USD（四宫格）。失败全额退款；本地 400 零扣费。

Suno 计费（按上游 cost USD）

与 Zhenzhen 扩展同属「上游 USD cost × 汇率」结算路径（多数生成类 action）：

计费公式
按任务完成后的实际上游消耗结算为人民币（部分工具类按次）；提交预扣，成功多退少补，失败全额退款。具体金额以控制台预估与余额变动为准。

实测参考：suno-generation @ v3.5 单次 cost≈0.05 USD（常出 2 轨）。部分工具类 action 无 cost，按次计费。提交失败 / 生成失败全额退款；本地 400 零扣费。

视频超分计费（Zhenzhen Upscaler）

按输入视频时长 × 目标分辨率单价结算，详见 视频超分。牌价：720p ¥0.14/s、1080p ¥0.21/s、2k ¥0.35/s、4k ¥0.56/s。与上方 Seedance「超分附加费」无关。

错误处理

HTTP场景响应示例
400 缺少必填参数（如 prompt） {"code":"invalid_request","message":"prompt is required"}
400 缺少任务类型所需素材（如 i2v 缺 images） {"code":"fail_to_fetch_task","message":"...image-to-video requires at least one input image..."}
401 鉴权失败 缺少或格式错误的 Authorization 头
429 上传接口超过频率限制 每令牌每分钟 30 次 / 每天 10000 次
503 model 不存在 / 未挂载 {"error":{"code":"model_not_found","message":"No available channel for model ..."}}

提交失败时不会真正扣费，预扣额度会全额退还。生成阶段失败通过查询接口的 status: "failed" 与 error 字段返回，同样全额退款。

Midjourney、Suno 与 Flow Music 完整 API 文档

路径与参数对齐本站 https://api.seedance.nz。请求 / 响应示例见右侧多语言卡片。

Flow Music 路径 SKU： flowmusic-generation · flowmusic-lyrics · flowmusic-extend · flowmusic-replace · flowmusic-cover · flowmusic-stems · flowmusic-upload-audio · flowmusic-download-audio · flowmusic-video-clip

Midjourney API 概览

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

  • Midjourney 文生图（Imagine）/ 垫图 / 二次操作 / 图生视频接口总览
  • 异步任务模式：提交后返回 task_id，轮询查询结果
  • 新版路由自动注入 model=midjourney，支持原生 MJ 参数、body 结构化参数与 metadata

Base URL： https://api.seedance.nz

鉴权： Authorization: Bearer <token>

新版 /v1/midjourney/... 路由会自动注入 model=midjourney，请求体不需要传 model。

快速开始

# 1. 提交绘图
curl -X POST https://api.seedance.nz/v1/midjourney/generations \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{"prompt": "a cute cat, watercolor style --ar 16:9"}'

# 2. 查询结果（推荐轮询统一任务接口直到 status=completed）
curl https://api.seedance.nz/v1/tasks/task_01JWXXXX \
 -H "Authorization: Bearer <token>"

# 3. 放大第1张图
curl -X POST https://api.seedance.nz/v1/midjourney/generations/upscale \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{"task_id": "task_01JWXXXX", "index": 1}'

接口总览

每个功能的完整字段、示例、注意事项见对应子页面。

功能 路径 文档
文生图（默认入口） POST /v1/midjourney/generations Imagine
文生图（显式入口） POST /v1/midjourney/generations/imagine Imagine
多图融合 POST /v1/midjourney/generations/blend Blend
图生文（识图） POST /v1/midjourney/generations/describe Describe
图片编辑 POST /v1/midjourney/generations/edits Edits
放大选图 POST /v1/midjourney/generations/upscale Upscale
生成变体 POST /v1/midjourney/generations/variation Variation
大幅变体 POST /v1/midjourney/generations/high-variation High Variation
微调变体 POST /v1/midjourney/generations/low-variation Low Variation
重新生成 POST /v1/midjourney/generations/reroll Reroll
缩放扩展 POST /v1/midjourney/generations/zoom Zoom
平移扩展 POST /v1/midjourney/generations/pan Pan
局部重绘 POST /v1/midjourney/generations/inpaint Inpaint
Modal 补充参数 POST /v1/midjourney/generations/modal Modal
图生视频 POST /v1/midjourney/generations/video Video
重塑（强 / 弱） POST /v1/midjourney/generations/remix-strong · /remix-subtle Remix
任务查询 GET /v1/tasks/{task_id} · /v1/midjourney/{task_id} 任务查询

参考：最佳实践（轮询 / 重试 / 排错） · 完整工作流示例（端到端 curl + 客户端封装）

完整使用流程

flowchart TB
 A["① POST /generations<br/>提交 Imagine"] --> B["② GET /v1/tasks/{task_id}<br/>轮询至 completed"]
 B --> C["③ 如需按钮<br/>GET /v1/midjourney/{task_id}"]
 C --> D1["/upscale"]
 C --> D2["/variation"]
 C --> D3["/reroll"]
 C --> D4["/zoom"]
 C --> D5["/inpaint<br/>(进入 MODAL)"]
 D5 --> M["/modal<br/>提交遮罩 + prompt"]

错误处理

错误响应格式

{
 "error": {
 "type": "invalid_request_error",
 "message": "prompt is required"
 }
}

常见错误

HTTP 状态码 type 说明
400 invalid_request_error 参数错误（缺少必填、格式错误等）
401 authentication_error API Key 无效
402 payment_required 余额不足
404 not_found 任务不存在
429 rate_limit_error 请求频率超限
500 internal_error 服务器内部错误

任务失败

fail_reason 常见值：

  • Banned prompt detected — 提示词含违禁内容
  • Task timeout — 任务超时（超过 30 分钟未完成），已自动退款
  • No available upstream — 服务暂不可用，请稍后重试

计费说明

MJ 新版统一模型名是 midjourney，通过 action、version、speed 生成计费 key。匹配顺序通常为：

midjourney@<action>-<version>-<speed>
-> midjourney@<action>-<version>
-> midjourney@<action>-<speed>
-> midjourney@<action>
-> midjourney
操作 计费名称 说明
Imagine midjourney@imagine[-version][-speed] 文生图 / 垫图
Blend midjourney@blend[-speed] 多图融合
Describe midjourney@describe[-speed] 图生文
Edits midjourney@edits[-speed] 图片编辑
Upscale midjourney@upscale[-version][-speed] 放大
Variation midjourney@variation[-version][-speed] 变体
High Variation midjourney@high_variation[-version][-speed] 强变体
Low Variation midjourney@low_variation[-version][-speed] 弱变体
Reroll midjourney@reroll[-version][-speed] 重新生成
Zoom midjourney@zoom[-version][-speed] 缩放扩图
Pan midjourney@pan[-version][-speed] 平移扩图
Inpaint midjourney@inpaint[-version][-speed] 局部重绘入口
Modal midjourney@modal[-speed] 局部重绘补参
Video midjourney@video / midjourney@video-720p 图生视频，实扣 × batch_size
Remix Strong midjourney@remix_strong[-speed] 强重塑（仅 v8.1 / v8.2）
Remix Subtle midjourney@remix_subtle[-speed] 弱重塑（仅 v8.1 / v8.2）

说明：

  • speed=relax 或未传 speed 时，不追加 speed 后缀；fast / turbo 会追加对应后缀。
  • 主版本归一化为 v8.2、v8.1、v7、v6.1、v5.2、v5.1。
  • niji=true + version=7/6 归一化为 niji7 / niji6。

具体价格以控制台模型定价页为准。任务失败会自动全额退款。

Imagine（文生图）

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

Midjourney 文生图 / 垫图。默认入口 /v1/midjourney/generations 与显式入口 /imagine 行为一致

默认文生图 / 垫图接口，等同于 imagine。显式入口 /v1/midjourney/generations/imagine 行为一致。

项目 内容
action IMAGINE
计费 midjourney@imagine[-version][-speed]
必填 prompt
可选 image_urls、Prompt 参数、speed、metadata

请求参数

字段 类型 必填 说明
prompt string 是 提示词，支持原生 MJ 参数（如 --ar 16:9 --v 6.1）
speed string 否 速度模式：relax（默认）/ fast / turbo
image_urls string[] 否 垫图 URL（图生图场景），支持 URL 或 base64
metadata object 否 自定义元数据，会随任务保存，便于业务侧追踪

结构化参数（可选）

以下参数可以写在 body 里，也可以直接写在 prompt 中（如 --ar 16:9）。body 优先级高于 prompt。

字段 类型 等价 MJ 参数 说明
size string --ar 宽高比，如 "16:9", "1:1", "9:16"
quality string --q 质量："0.25", "0.5", "1", "2"
style string --style 风格："raw" 等
version string --v 版本号。主版本会追加为 --v <version>；与 niji: true 搭配 "7" / "6" 时会归一化为 Niji 版本
seed int --seed 随机种子
negative_prompt string --no 负面提示词，如 "ugly, blurry"
stylize int --s 风格化强度 (0-1000)
chaos int --c 混乱度 (0-100)
weird int --w 怪异度 (0-3000)
tile bool --tile 平铺模式
niji bool --niji Niji 开关。推荐传 niji: true + version: "7" / "6"
iw float --iw 图片权重 (0-3)，垫图时使用
cw int --cw 角色权重 (0-100)
sw int --sw 风格权重 (0-1000)
cref string --cref 角色参考图 URL
sref string --sref 风格参考图 URL
dref string --dref 深度参考图 URL
dw float --dw 深度权重 (0-100)
repeat int --repeat 重复生成次数 (2-40)
raw bool --raw 原始风格 (v5.1+ 支持)
draft bool --draft 草图模式 (v7+ 支持)
hd bool --hd HD 高清 (仅 v8.1 / v8.2，未传 version 时后端自动补 --v 8.1)
stop int --stop 提前停止 (10-100，仅 v5-6.1 / niji 5-6)
extra string 任意 --xxx 逃生口，原样追加到 prompt 末尾

示例

方式一：参数写在 prompt 里

{
 "prompt": "a beautiful sunset over mountains --ar 16:9 --v 6.1 --style raw --s 750"
}

方式二：参数写在 body 里（推荐）

{
 "prompt": "a beautiful sunset over mountains",
 "size": "16:9",
 "version": "6.1",
 "style": "raw",
 "stylize": 750
}

主版本与 Niji 版本

{
 "prompt": "anime girl in a moonlit garden",
 "niji": true,
 "version": "7",
 "size": "9:16"
}

线上已验证可用版本：8.2、8.1、7、6.1、5.2、5.1、niji 7、niji 6。主版本使用 body 字段 version；Niji 推荐传 niji: true + version: "7" / "6"，计费版本会归一化为 niji7 / niji6。

方式三：混合使用（body 优先）

{
 "prompt": "a beautiful sunset --ar 1:1",
 "size": "16:9"
}

最终 prompt: a beautiful sunset --ar 16:9（body 中的 size 覆盖了 prompt 中的 --ar 1:1）

图生图（垫图）

{
 "prompt": "turn this product into a luxury studio photo",
 "image_urls": ["https://example.com/product.png"],
 "size": "1:1",
 "iw": 1.2
}

Fast 模式

{
 "prompt": "a cute cat",
 "speed": "fast"
}

speed=relax 或未传 speed 时不追加计费 speed 后缀；fast / turbo 会通过对应速度通道生效，并匹配对应计费 key。

响应

{
 "code": 200,
 "data": [{
 "status": "submitted",
 "task_id": "task_01JWXXXXXXXXXXXX"
 }]
}

成功后通过任务查询轮询结果。

Blend（多图融合）

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

将 2–4 张图融合成一张新图（MJ 经典 blend），完全靠图融合，不支持 prompt

将 2–4 张图融合成一张新图（MJ 经典 blend 功能），完全靠图融合，不支持 prompt 参数。

项目 内容
action BLEND
计费 midjourney@blend[-speed]
必填 image_urls（2–4 张）

参数

字段 类型 必填 默认 说明
image_urls string[] 是 — 垫图，2–4 张，后端自动转 base64；单图 ≤ 12 MiB
dimensions string 否 SQUARE 三档画面比例：SQUARE(1:1) / PORTRAIT(2:3) / LANDSCAPE(3:2)；传了 size 时被覆盖
size string 否 — 自由比例，任意 w:h（如 "16:9"、"9:16"、"21:9"），优先级高于 dimensions，作为画面比例生效
speed string 否 relax relax / fast / turbo
metadata object 否 — 自定义元数据

请求示例

三档比例（dimensions）：

{
 "image_urls": [
 "https://example.com/a.png",
 "https://example.com/b.png"
 ],
 "dimensions": "SQUARE",
 "speed": "fast"
}

自由比例（size）：

{
 "image_urls": [
 "https://example.com/a.png",
 "https://example.com/b.png"
 ],
 "size": "16:9",
 "speed": "fast"
}

最终 prompt 末尾会带 --ar 16:9。

注意

  • 比例选择优先级：size（自由） > dimensions（三档） > 默认 SQUARE。
  • image_urls 少于 2 张或多于 4 张返回 400。
  • blend 没有独立版本参数；如需区分速度价格，可配置 midjourney@blend-fast / midjourney@blend-turbo。

Describe（图生文）

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

图片反推 prompt，同步返回（1–3s），结果在 prompt / description 字段

图片反推 prompt。通常 1–3s 同步返回，但仍走平台标准异步流——提交后照常轮询查询。

项目 内容
action DESCRIBE
计费 midjourney@describe[-speed]
必填 image_urls（1 张）

参数

字段 类型 必填 默认 说明
image_urls string[] 是 — 单张图；数组形式，多传只取第一张；单图 ≤ 12 MiB
speed string 否 relax relax / fast / turbo
metadata object 否 — 自定义元数据

请求示例

{
 "image_urls": ["https://example.com/input.png"],
 "speed": "fast"
}

响应

文字结果在查询结果的 prompt / description，不返回 image_urls / grid_image_url。反推为 4 段带编号建议，用 \n 分隔、数字 emoji 1️⃣2️⃣3️⃣4️⃣ 前缀：

{
 "id": "task_xxx",
 "status": "SUCCESS",
 "action": "DESCRIBE",
 "mode": "DESCRIBE",
 "prompt": "1️⃣ a serene mountain lake at sunrise --ar 3:2\n2️⃣ mountain landscape with reflections --v 6.1\n3️⃣ panoramic view of alpine lake --ar 16:9\n4️⃣ dawn light over still water --s 250",
 "description": "1️⃣ a serene mountain lake at sunrise --ar 3:2\n..."
}

注意

  • describe 为独立处理通道，不占用普通生图的并发额度。
  • 通常 1–3s 同步返回，但仍需轮询 GET /v1/tasks/{task_id}（或 GET /v1/midjourney/{task_id}）拿结果。
  • 缺图返回 400；单图超 12 MiB 返回 400。

Edits（图片编辑）

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

基于已有图 + prompt 改写整张图。适合背景替换、风格迁移、内容修改

基于已有图 + prompt 改写整张图。适合背景替换、风格迁移、内容修改。

项目 内容
action EDITS
计费 midjourney@edits[-speed]
必填 prompt + image_urls

参数

字段 类型 必填 默认 说明
prompt string 是 — 编辑指令
image_urls string[] 是 — 待编辑图；单图 ≤ 12 MiB
speed string 否 relax relax / fast / turbo
metadata object 否 — 自定义元数据

结构化参数（可选）

同 Imagine，可写在 body 里或 prompt 中（如 --ar 16:9），body 优先级高于 prompt，会拼到 prompt 末尾并覆盖同名手写 flag。

字段 类型 等价 MJ 参数 说明
size string --ar 宽高比，如 "16:9", "1:1", "9:16"
quality string --q 质量："0.25", "0.5", "1", "2"
style string --style 风格："raw" 等
version string --v 版本号。主版本会追加为 --v <version>；与 niji: true 搭配 "7" / "6" 时会归一化为 Niji 版本
seed int --seed 随机种子
negative_prompt string --no 负面提示词，如 "ugly, blurry"
stylize int --s 风格化强度 (0-1000)
chaos int --c 混乱度 (0-100)
weird int --w 怪异度 (0-3000)
tile bool --tile 平铺模式
niji bool --niji Niji 开关。推荐传 niji: true + version: "7" / "6"
iw float --iw 图片权重 (0-3)，垫图时使用
cw int --cw 角色权重 (0-100)
sw int --sw 风格权重 (0-1000)
cref string --cref 角色参考图 URL
sref string --sref 风格参考图 URL
dref string --dref 深度参考图 URL
dw float --dw 深度权重 (0-100)
repeat int --repeat 重复生成次数 (2-40)
raw bool --raw 原始风格 (v5.1+ 支持)
draft bool --draft 草图模式 (v7+ 支持)
hd bool --hd HD 高清 (仅 v8.1 / v8.2，未传 version 时后端自动补 --v 8.1)
stop int --stop 提前停止 (10-100，仅 v5-6.1 / niji 5-6)
extra string 任意 --xxx 逃生口，原样追加到 prompt 末尾

请求示例

{
 "prompt": "replace the background with a modern kitchen, keep the product unchanged --ar 1:1",
 "image_urls": ["https://example.com/product.png"],
 "version": "8.1",
 "speed": "fast"
}

响应

提交返回 task_id，SUCCESS 后含编辑结果 image_urls（可能 1–4 张）+ grid_image_url。

注意

  • 与 imagine 垫图的区别：edits 重在"改写整张图"，imagine + 垫图重在"参考风格"。
  • 缺 prompt 或 image_urls 返回 400；单图超 12 MiB 返回 400。

Upscale（放大选图）

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

对 Imagine 四宫格选取 U1–U4 中的一张得到单图，本地合成、通常瞬时返回

对父任务四宫格（grid_image_url）选取 U1–U4 中的一张，得到单图。通过从已有 4 张图里截取实现，本地合成、通常瞬时返回。

项目 内容
action UPSCALE
计费 midjourney@upscale[-version][-speed]
必填 task_id + index，或 task_id + custom_id
可选 speed、metadata

参数

字段 类型 说明
task_id string 父任务 ID（须为 imagine / variation / reroll 等 SUCCESS 任务）
index int 选第几张（U1–U4），范围 1–4；与 custom_id 二选一
custom_id string 直接传对应操作的按钮 ID；与 index 二选一，传了它就不按 index 匹配
speed string relax / fast / turbo（本地合成，实际无影响）
metadata object 自定义元数据

请求示例

按 index 选图：

{
 "task_id": "task_01KQVZAPBW13W63DQNQZT7FCQK",
 "index": 1,
 "speed": "fast"
}

直接传按钮：

{
 "task_id": "task_01KQVZAPBW13W63DQNQZT7FCQK",
 "custom_id": "MJ::JOB::upsample::1::xxxx"
}

响应

提交返回新 task_id，通常毫秒级即 SUCCESS。SUCCESS 后 image_urls 只有 1 个元素（单图），buttons 含可继续的操作（zoom / inpaint / pan / variation 等）。

注意

  • 父任务必须是 SUCCESS 状态，否则返回 400（task is not in SUCCESS state）。
  • index 必须 1–4，越界返回 400；custom_id 与 index 二选一，都传时 custom_id 优先。
  • 真正消耗资源的是 imagine 阶段，upscale 只是从已有图里挑，几乎不会失败。
  • upscale 后的单图可继续用 Zoom / Inpaint / Variation。

HD upscale（高清放大，输出 2x 单图）

普通 upscale 是本地合成——从父任务已有的 4 张图里截取其中一张，瞬时返回。如果后续要对单图做 zoom / inpaint 等精细操作，建议改用 HD upscale：执行真实放大，输出 2x 高清单图，约 60–120s 完成，产出的单图能更稳定地支持后续 zoom / inpaint。

HD upscale 通过 custom_id 指定放大命令，不同 imagine 版本对应不同命令：

customId 命令 适用版本
upsample_v5_2x v5 imagine
upsample_v5_4x v5 imagine
upsample_v6_2x_subtle v6 / v6.1 imagine
upsample_v6_2x_creative v6 / v6.1 imagine
upsample_v7_2x_subtle v7 / v8.1 imagine
upsample_v7_2x_creative v7 / v8.1 imagine

HD upscale 示例

{
 "task_id": "task_01KQVZAPBW13W63DQNQZT7FCQK",
 "custom_id": "MJ::JOB::upsample_v7_2x_subtle::1::xxxx"
}

完成后得到一张真正的 2x 高清单图任务，可继续对它做 zoom / inpaint。

与普通 upscale 对比

维度 普通 upscale HD upscale
实现 本地合成（截取） 真实放大处理
耗时 毫秒级 约 60–120s
输出 4 张里取第 N 张 2x 高清单图
后续 zoom / inpaint / variation zoom / inpaint 更稳定

⚠️ pan 仍不可用

即使是 HD upscale 产出的高清单图，pan 操作仍会被拒（返回"无效生图请求"）——这是 Midjourney 对 pan 操作本身的限制，与放大方式无关。详见 Pan。

Variation（生成变体）

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

对 Imagine 四宫格的某一张做弱变体（varySubtle，等价 V1–V4）

对 imagine 四宫格里的某一张做弱变体（varySubtle，等价 V1–V4）。强变体见 High Variation。

项目 内容
action VARIATION
计费 midjourney@variation[-speed]
必填 task_id + index，或 task_id + custom_id
可选 speed、metadata

参数

字段 说明
task_id 本平台返回的原任务 ID（须为 SUCCESS）
index 1–4，对应 V1–V4；与 custom_id 二选一
custom_id 直接指定对应操作的按钮 ID，传了它就不按 index 自动匹配
speed relax / fast / turbo
metadata 自定义元数据

请求示例

{
 "task_id": "task_01KQVZAPBW13W63DQNQZT7FCQK",
 "index": 3,
 "speed": "turbo"
}

响应

提交返回新的本地 task_id，轮询 GET /v1/tasks/{task_id}，SUCCESS 后含变体的新四宫格 grid_image_url + 4 张 image_urls：

{
 "id": "task_xxx",
 "status": "SUCCESS",
 "action": "VARIATION",
 "grid_image_url": "...",
 "image_urls": ["...", "...", "...", "..."]
}

来源任务的 version / niji 会自动继承（影响计费 fallback）；如需区分速度价格，可配置 midjourney@variation-fast / midjourney@variation-turbo。

注意

  • 父任务必须是 SUCCESS 状态，否则返回 400（task is not in SUCCESS state）。
  • index 必须 1–4；custom_id 与 index 二选一。
  • 默认走 varySubtle（弱变体）；强变体用 High Variation；Low Variation 是同 action 不同计费 key，行为相同。

High Variation（大幅变体）

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

对已 upscale 的单图做强变体（varyStrong，对应 Vary (Strong)）

对已 upscale 的单图做强变体（varyStrong，对应 Vary (Strong)，变化幅度大、偏离原图更多）。弱变体见 Variation。

项目 内容
action HIGH_VARIATION
计费 midjourney@high_variation[-speed]
必填 task_id + index，或 task_id + custom_id
可选 speed、metadata

参数

字段 说明
task_id 本平台返回的任务 ID（通常为 Upscale 后的单图任务）
index 1–4；未传 custom_id 时必填，按钮匹配不使用 index
custom_id 直接指定对应操作的按钮 ID；传入后不按 index 自动匹配
speed relax / fast / turbo
metadata 可选，自定义元数据

自动匹配

优先匹配 Vary (Strong)，失败回退 Make Variations。

请求示例

{
 "task_id": "task_01KQW0D3WJ2QYJP9E3H7GZ4D2R",
 "index": 1,
 "speed": "fast"
}

注意

  • 通常先对四宫格调用 upscale，再拿 upscale 产生的新 task_id 调用本接口。
  • 当前实现中未传 custom_id 时仍要求 index，虽然按钮匹配本身不使用 index。
  • 来源任务的版本 metadata 会自动继承；如需区分速度价格，可配置 midjourney@high_variation-fast / midjourney@high_variation-turbo。

返回

提交成功返回新的本地 task_id，请轮询 GET /v1/tasks/{task_id} 查询结果。

Low Variation（微调变体）

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

对已 upscale 的单图做弱变体（varySubtle，与 Variation 行为一致，仅计费 key 不同）

对已 upscale 的单图做弱变体（varySubtle，与 Variation 行为完全一致）。独立 endpoint 主要用于命名一致性（与 High Variation 对偶）和价格独立配置；新接入推荐直接用 Variation。

项目 内容
action LOW_VARIATION
计费 midjourney@low_variation[-speed]
必填 task_id + index，或 task_id + custom_id
可选 speed、metadata

参数

字段 说明
task_id 本平台返回的任务 ID（通常为 Upscale 后的单图任务）
index 1–4；未传 custom_id 时必填，按钮匹配不使用 index
custom_id 直接指定对应操作的按钮 ID；传入后不按 index 自动匹配
speed relax / fast / turbo
metadata 可选，自定义元数据

自动匹配

优先匹配 Vary (Subtle)，失败回退 Make Variations。

请求示例

{
 "task_id": "task_01KQW0D3WJ2QYJP9E3H7GZ4D2R",
 "index": 1,
 "speed": "fast"
}

注意

  • 通常先对四宫格调用 upscale，再拿 upscale 产生的新 task_id 调用本接口。
  • 当前实现中未传 custom_id 时仍要求 index，虽然按钮匹配本身不使用 index。
  • 来源任务的版本 metadata 会自动继承；如需区分速度价格，可配置 midjourney@low_variation-fast / midjourney@low_variation-turbo。

返回

提交成功返回新的本地 task_id，请轮询 GET /v1/tasks/{task_id} 查询结果。

Reroll（重新生成）

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

基于父任务 prompt 重新抽 4 张图（等价 🔄 重抽按钮），整网格重抽无需 index

基于父任务的 prompt 重新抽 4 张图（等价 🔄 重抽按钮）。整个网格重抽，无需 index。

项目 内容
action REROLL
计费 midjourney@reroll[-speed]
必填 task_id，或 task_id + custom_id
可选 speed、metadata

参数

字段 说明
task_id 本平台返回的原任务 ID
custom_id 可选，直接指定 reroll 对应操作的按钮 ID
speed relax / fast / turbo
metadata 可选，自定义元数据

自动匹配

服务端会从原任务 buttons 中匹配包含 ::reroll:: 的按钮，或匹配 reroll emoji。

请求示例

{
 "task_id": "task_01KQVZAPBW13W63DQNQZT7FCQK",
 "speed": "fast"
}

错误响应

HTTP code description
400 4 task_id is required for reroll
400 4 task ... is not in SUCCESS state
404 3 task ... not found
502 9 服务拒绝

返回

提交成功返回新的本地 task_id，请轮询 GET /v1/tasks/{task_id}，SUCCESS 后是同 prompt 的全新四宫格。

来源任务的 prompt / version / niji / 结构化参数会自动继承（种子可能不同，因此结果不同）；如需区分速度价格，可配置 midjourney@reroll-fast / midjourney@reroll-turbo。

注意

  • 只能 reroll imagine 或自身 reroll 产生的网格任务；不能 reroll 已做过 upscale / variation / pan 等二次操作的任务。
  • 父任务必须是 SUCCESS 状态。

Zoom（缩放扩展）

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

对已 upscale 的单图执行 Zoom Out 扩图，原图保留向外补背景（Outpaint / CustomZoom）

对已 upscale 的单图执行 Zoom Out（扩图缩放）：原图保留，向外补充更多背景。zoom_ratio < 2 走 Outpaint（1.5×），≥ 2 或未传走 CustomZoom（2×），两者均直接出图。

项目 内容
action ZOOM
计费 midjourney@zoom[-speed]
必填 task_id，或 task_id + custom_id
可选 zoom_ratio、index、speed、metadata

参数

字段 说明
task_id 本平台返回的任务 ID（须为 Upscale 后的单图任务）
custom_id 可选，直接指定 Zoom 对应操作的按钮 ID
index 可选，选父任务第几张（1–4，默认 1）；单图通常不用动
zoom_ratio 可选，决定自动匹配的 Zoom Out 档位（见下表）
speed relax / fast / turbo
metadata 可选

自动匹配

zoom_ratio 匹配按钮
小于 2 Zoom Out 1.5x
未传或 >= 2 Zoom Out 2x

请求示例

{
 "task_id": "task_01KQW0D3WJ2QYJP9E3H7GZ4D2R",
 "zoom_ratio": 1.5,
 "speed": "fast"
}

注意

  • 父任务必须是已 upscale 的单图且为 SUCCESS；传四宫格会返回 This action requires an upscaled task...，需先调用 upscale。
  • Outpaint / CustomZoom 均直接出图，无需 mask，不进 MODAL（只有 Inpaint 走 MODAL）。
  • 来源任务的版本 metadata 会自动继承；如需区分速度价格，可配置 midjourney@zoom-fast / midjourney@zoom-turbo。

返回

提交成功返回新的本地 task_id，请轮询 GET /v1/tasks/{task_id} 查询结果。

Pan（平移扩展）

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

对已 upscale 的单图向指定方向接图扩展，可连续 pan 拼全景（仅 v6/v6.1/v7/v8.1/v8.2/niji6）

对已 upscale 的单图向指定方向"接图"扩展：原图保留在边缘，新方向区域补全。可连续 pan（向右后继续向右），适合拼全景图。

项目 内容
action PAN
计费 midjourney@pan[-speed]
必填 task_id + direction，或 task_id + custom_id
可选 index、speed、metadata

参数

字段 说明
task_id 本平台返回的任务 ID（须为 Upscale 后的单图任务）
direction left / right / up / down
custom_id 可选，直接指定 Pan 对应操作的按钮 ID；指定后不必再传 direction
index 可选（1–4），backend 自动转 0-based
speed relax / fast / turbo
metadata 可选

自动匹配按 customId 子串：pan_left、pan_right、pan_up、pan_down。

请求示例

{
 "task_id": "task_01KQW0D3WJ2QYJP9E3H7GZ4D2R",
 "direction": "right",
 "speed": "fast"
}

注意

  • 版本限制：pan 仅适用于 v6 / v6.1 / v7 / v8.1 / v8.2 / niji 6；v5.2 及更早会 FAILURE（MJ engine 跑不出）。
  • 如果返回 This action requires an upscaled task...，说明传入的是四宫格任务，需要先调用 upscale。
  • direction 必须是 left / right / up / down 之一。
  • 来源任务的版本 metadata 会自动继承；如需区分速度价格，可配置 midjourney@pan-fast / midjourney@pan-turbo。

返回

提交成功返回新的本地 task_id，请轮询 GET /v1/tasks/{task_id} 查询结果。

Inpaint（局部重绘）

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

局部重绘入口（等价 Vary (Region)），提交后进 MODAL，需再调 modal 上传 mask + prompt

局部重绘入口（等价 Vary (Region)）。提交后任务进 MODAL 状态，需再调 modal 上传 mask + prompt 才能完成。

项目 内容
action INPAINT
计费 midjourney@inpaint[-version][-speed]
必填 task_id，或 task_id + custom_id
可选 index、speed、metadata

参数

字段 说明
task_id 原任务 ID（一般为 Upscale 后的单图任务）
custom_id 可选，直接指定 Vary (Region) 对应操作的按钮 ID
index 可选，选父任务第几张（1–4，默认 1）；单图通常不用动
speed relax / fast / turbo
metadata 可选

自动匹配

服务端从原任务 buttons 中匹配 Vary (Region)。

请求示例

{
 "task_id": "task_01KQW0D3WJ2QYJP9E3H7GZ4D2R",
 "speed": "fast"
}

后续流程

提交成功后返回 status: "modal"——这是合法非终态，不是错误。请用 modal 接口继续：其中 task_id 为上一步 inpaint 返回的本地任务 ID，并提交 prompt 以及可选 mask_url。

{
 "task_id": "task_03_inpaint...",
 "status": "modal",
 "model": "midjourney"
}

注意

  • 父任务必须是 SUCCESS 的 upscale 单图；四宫格直接 inpaint 会报错，需先 upscale。
  • 进入 MODAL 后 30 分钟内必须调 modal 补参，否则后台自动 CANCEL + 退款。
  • 来源任务的版本 metadata 会自动继承；如需区分速度价格，可配置 midjourney@inpaint-fast / midjourney@inpaint-turbo。

Modal（提交补充参数）

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

给 MODAL 状态的局部重绘任务补充 mask + prompt 完成重绘

给 MODAL 状态的局部重绘任务补充 mask + prompt 完成重绘。系统按 mask_url 是否存在自动判断模式：有 mask_url → 局部重绘；无 → 外扩。

项目 内容
action MODAL
计费 midjourney@modal[-speed]
必填 task_id
可选 prompt、mask_url、speed、metadata

参数

字段 说明
task_id inpaint 步骤返回的本地任务 ID（须为 MODAL 状态）
prompt 局部重绘提示词；留空则继承父任务 prompt
mask_url 遮罩图 URL 或 base64；局部重绘时必填。透明区域=要重绘的位置，白色区域=保留原图
speed relax / fast / turbo
metadata 可选

mask 要求

项 建议
格式 PNG 透明背景（也支持 data:image/png;base64,...）
分辨率 建议与父图同分辨率（系统也会自动 resize）
透明区域 要重绘的位置；白色区域保留原图
大小 单图 ≤ 12 MiB
URL 必须公网可达（私网会被 SSRF 拦截）

请求示例

{
 "task_id": "task_01KQW1N9T6E3AHW6QZFDEK8M5C",
 "prompt": "replace the selected area with a red leather sofa",
 "mask_url": "https://example.com/mask.png",
 "speed": "fast"
}

返回

task_id 不变（同一任务），status 从 MODAL → SUBMITTED。轮询 GET /v1/tasks/{task_id}，SUCCESS 后 image_urls 含 4 张局部重绘候选。计费在本接口 SUCCESS 时结算，与 inpaint 阶段不重复扣费。

如需区分速度价格，可配置 midjourney@modal-fast / midjourney@modal-turbo。

Video（图生视频）

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

Midjourney 图生视频（i2v），固定 FAST，不支持 t2v，时长约 5 秒

图生视频（i2v）。固定 FAST 模式，无 speed 维度；不支持纯文生视频（t2v），必须给首帧。时长固定约 5 秒。

项目 内容
action VIDEO
计费 midjourney@video / midjourney@video-720p，实扣 = 单价 × batch_size
必填 image_urls（首帧）或 task_id（复用 imagine SUCCESS）

参数

字段 类型 必填 默认 说明
prompt string 否 （继承父任务） 视频提示词；为空时必须有 task_id
image_urls string[] △ — 起始帧（1 张，≤ 12 MiB）；与 task_id 二选一
task_id string △ — 复用已有 imagine SUCCESS；与 image_urls 二选一
index int 否 — 从 imagine 4 张图选哪张作首帧（0–3，配合 task_id）
video_type string 否 vid_1.1_i2v_480 分辨率档（见下表）；含 720 → 走 @video-720p 计费
animate_mode string 否 manual manual / auto；auto 必须给 task_id + index
motion string 否 high low / high；运动幅度，不影响计费
batch_size int 否 1 必须 1 / 2 / 4，其他值视为 1；计费 × N
end_url string 否 — 结束帧；设了后 video_type 自动升级为 start_end_*

video_type 合法值

值 分辨率 模式 命中价格
vid_1.1_i2v_480 480p 基础 i2v（默认） midjourney@video
vid_1.1_i2v_720 720p 基础 i2v midjourney@video-720p
vid_1.1_i2v_start_end_480 480p 起止帧（传 end_url 时自动升级） midjourney@video
vid_1.1_i2v_start_end_720 720p 起止帧（传 end_url 时自动升级） midjourney@video-720p

不接受带 extend 的取值；仅支持上表列出的 video_type。

请求示例

简单 i2v（自带首帧，batch 4）：

{
 "prompt": "the cat slowly turns its head to the camera",
 "image_urls": ["https://example.com/cat.png"],
 "motion": "high",
 "batch_size": 4
}

起止帧 transition（传 end_url 自动升级为 start_end）：

{
 "prompt": "transition smoothly from sunrise to sunset",
 "image_urls": ["https://example.com/sunrise.jpg"],
 "end_url": "https://example.com/sunset.jpg",
 "video_type": "vid_1.1_i2v_720"
}

响应

提交返回 task_id，轮询 GET /v1/tasks/{task_id}。SUCCESS 后含 video_url（首个）+ video_urls（length === batch_size，batch=1 时也是 1 个元素）：

{
 "id": "task_xxx",
 "status": "SUCCESS",
 "action": "VIDEO",
 "mode": "FAST",
 "video_url": "https://r2.example.com/video-0.mp4",
 "video_urls": [
 "https://r2.example.com/video-0.mp4",
 "https://r2.example.com/video-1.mp4"
 ]
}

注意

  • 不支持纯文生视频（t2v）：必须给 image_urls 或 task_id，否则返回 400；两者不能同时传。
  • 固定 FAST 模式，无 speed 维度（计费表里 @video-fast / @video-turbo 永不命中）。
  • batch_size 严格校验为 1 / 2 / 4；batch=4 实扣 4 倍，预算敏感时用 batch=1。
  • animate_mode=auto 必须同时给 task_id + index。
  • 首帧 / 结束帧单图 ≤ 12 MiB。

Remix（重塑，仅 v8.1 / v8.2）

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

v8 操作面板的重塑（reshape），把父图重新生成可改 prompt，分强 / 弱两档

v8 操作面板新增的"重塑"（reshape）：把父图重新生成，可改 prompt。仅 v8.1 / v8.2 父任务可用；v7 / v6 父图请改用 Variation / High Variation。

POST /v1/midjourney/generations/remix-strong
POST /v1/midjourney/generations/remix-subtle

v8 操作面板移除了 U1-U4 / zoom / outpaint / inpaint。对应替代：变化 → Variation / High Variation；重塑 → 本接口；重新生成 → Reroll。

项目 内容
action REMIX_STRONG / REMIX_SUBTLE
计费 midjourney@remix_strong[-speed] / midjourney@remix_subtle[-speed]
必填 task_id + index

参数

字段 类型 必填 默认 说明
task_id string 是 — 父任务（v8.1 / v8.2 imagine SUCCESS）
index int 是 — 选父图第几张做重塑（1–4）
prompt string 否 （继承父任务） 重塑用的新 prompt；空则用父图 prompt
speed string 否 relax relax / fast / turbo

力度对比

接口 op 改动幅度 类比
/remix-strong remixStrong 大幅改动，构图 / 风格都可能变 类似 High Variation（强变体）
/remix-subtle remixSubtle 小幅改动，保持主体 / 色调 类似 Variation（弱变体）

请求示例

强烈重塑：

{
 "task_id": "task_<v8_imagine_id>",
 "index": 1,
 "speed": "fast"
}

自定义 prompt 透传生效，可改风格 / 添加细节。

响应

提交返回新的本地 task_id，轮询 GET /v1/tasks/{task_id}，SUCCESS 后含 4 张重塑图。

注意

  • 仅 v8.1 / v8.2 父图可用；父任务非 v8 系列返回 400。
  • v7 / v6 父图请用 Variation / High Variation / Low Variation。

任务查询

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

查询 Midjourney 任务状态与结果。统一任务接口 /v1/tasks/{task_id} 与 MJ 风格接口 /v1/midjourney/{task_id}

推荐业务侧轮询统一任务接口：

GET /v1/tasks/{task_id}

统一任务状态为 pending / processing / completed / failed，成功结果位于 result.images[].url。

需要读取 buttons[].customId 做二次操作时，使用 MJ 风格查询：

GET /v1/midjourney/{task_id}

任务状态流转

SUBMITTED → IN_PROGRESS → SUCCESS
 → FAILURE
 → MODAL（需补充参数，见局部重绘）

响应示例

{
 "id": "task_01JWXXXX",
 "status": "SUCCESS",
 "action": "IMAGINE",
 "progress": "100%",
 "grid_image_url": "https://cdn.example.com/mj_xxxx.png",
 "image_urls": [
 "https://cdn.example.com/mj_xxxx_0.png",
 "https://cdn.example.com/mj_xxxx_1.png",
 "https://cdn.example.com/mj_xxxx_2.png",
 "https://cdn.example.com/mj_xxxx_3.png"
 ],
 "buttons": [
 {"customId": "MJ::JOB::upsample::1::abc123def456", "label": "U1"},
 {"customId": "MJ::JOB::variation::1::abc123def456", "label": "V1"}
 ],
 "prompt": "a beautiful sunset over mountains"
}

grid_image_url 是四宫格合成大图，image_urls 是裁剪后的 4 张单图 URL 数组。

字段差异提醒

  • /v1/tasks/{task_id} 返回统一 pending / processing / completed / failed 状态。
  • /v1/midjourney/{task_id} 返回 MJ 风格字段，如 grid_image_url、image_urls、buttons。 关于 buttons： 大部分二次操作可传 index、direction 或 zoom_ratio，系统会自动匹配对应 customId；如自动匹配失败，可直接传 custom_id。

状态字段总览

status 含义 终态
NOT_START 已建行，系统未确认（瞬时态） 否
SUBMITTED 系统接受，排队中 否
IN_PROGRESS 系统处理中 否
MODAL 等待调 /modal 补参（见局部重绘） 否
SUCCESS 完成 ✓
FAILURE 失败 → 自动退款（quota 归 0，fail_reason 含原因） ✓

查询说明

  • 查询接口不单独计费，但建议合理控制频率（推荐 3–5s 轮询一次）。
  • 普通用户只能查自己的任务；查他人任务返回 403。
  • 任务默认保留 3 天，过后查询返回 404，但生成的图片 / 视频 URL 仍可访问。

高级：使用 custom_id 直接操作

读取 buttons[].customId 后，可直接传给二次操作接口的 custom_id 字段，绕过自动匹配：

{
 "task_id": "task_01JWXXXX",
 "custom_id": "MJ::JOB::upsample::1::abc123def456"
}

最佳实践

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

Midjourney 接入的轮询模式、Prompt 设计、垫图、错误重试策略、并发与排错建议

整合常见问题、性能优化、错误处理的最佳实践，接入前建议通读。

任务提交与轮询

提交接口都是异步任务：提交后返回 task_id，再周期性查询 GET /v1/midjourney/{task_id} 拿状态，直到 SUCCESS / FAILURE。

import time, httpx

def wait_task(task_id, timeout=300):
 deadline = time.time() + timeout
 while time.time() < deadline:
 resp = httpx.get(f"{HOST}/v1/midjourney/{task_id}",
 headers={"Authorization": f"Bearer {API_KEY}"}).json()
 if resp["status"] in ("SUCCESS", "FAILURE"):
 return resp
 if resp["status"] == "MODAL":
 raise RuntimeError(f"task {task_id} 需要调 /modal 补参完成")
 time.sleep(3)
 raise TimeoutError(task_id)
  • 轮询节奏：建议 3–5s 一次，更高频无意义且浪费配额。
  • 不要在 web 请求里同步阻塞等任务完成 —— 提交后立即返回 task_id，让前端异步轮询。

Prompt 设计

好的 prompt：

a serene mountain lake at sunrise, photorealistic, soft golden light,
mist rising from water, snow-capped peaks in distance --ar 16:9 --v 8.1 --s 100
  • 主体在前：先主体，再描述场景，最后修饰词。
  • 结构化参数显式：用 --ar / --v / --s（或对应 body 字段）比依赖默认值更可控。
  • 避免歧义词：photorealistic 比 realistic 更明确。

避免： 过于抽象（"make it good"）、主体散乱（多个并列对象不分主次）、给词加引号（会被当字面值）。

Niji 动漫： 传 niji: true + version: "7"，平台归一化为 --niji 7，计费走 midjourney@imagine-niji7。

垫图最佳实践

来源 推荐做法 注意
用户上传 先存自己的 OSS / CDN，提交时传该 URL 不要直接传 base64（浪费带宽）
公开 URL 直接传 注意 SSRF（须公网可达）与 12 MiB 限制
第三方 / 其他产物 先转存到自己的 OSS 第三方 URL 可能过期
  • 压缩到 \< 5 MiB：平台上限 12 MiB，但小图传输 / 处理都更快。
  • 格式 PNG / JPG / WebP 均可，推荐高质量 JPG。
  • 分辨率 1024–2048 px 已足够，更高浪费。
  • 垫图权重 iw（0–3，默认 1）：>1 更贴原图，\<1 更自由。

错误处理与重试策略

code 含义 重试策略
1 / 200 成功 ✅
4 VALIDATION_ERROR 参数错 ❌ 不要重试，修正参数
3 NOT_FOUND 无可用实例 / task_id 不存在 实例不可用可稍后重试；task_id 不存在不要重试
9 FAILURE 服务拒绝 / 内部错误 ⏳ 可重试，指数退避（1s, 4s, 16s）
21 MODAL 非终态 ✅ 继续调 /modal
24 BANNED_PROMPT 敏感词 ❌ 不要重试，改 prompt；已自动退款
429 限流 ⏳ 指数退避 + jitter
5xx / 网络错 服务端 / 网络 ⏳ 指数退避，网络错可立即重试 1 次 
import time, random, httpx

def submit_with_retry(payload, max_attempts=5):
 for attempt in range(max_attempts):
 try:
 r = httpx.post(f"{HOST}/v1/midjourney/generations/imagine",
 json=payload,
 headers={"Authorization": f"Bearer {API_KEY}"},
 timeout=30)
 data = r.json()
 if r.status_code == 200 and data["code"] in (1, 200):
 return data
 if data["code"] in (4, 24):
 raise ValueError(data["description"]) # 不可重试
 if data["code"] == 3 and "task" in data["description"]:
 raise ValueError(data["description"]) # task_id 不存在
 # 其余（9 / 429 / 5xx）可重试
 except httpx.RequestError:
 pass
 time.sleep((4 ** attempt) + random.uniform(0, 1)) # 1s / 4s / 16s ...
 raise RuntimeError(f"达到最大重试次数 {max_attempts}")

二次操作流程

# imagine → 轮询 → upscale
imagine_id = submit({"prompt": "a cat"})["data"][0]["task_id"]
result = wait_task(imagine_id) # grid_image_url + 4 张 image_urls + buttons
upscale_id = submit_to("/upscale", {"task_id": imagine_id, "index": 2})["data"][0]["task_id"]
final = wait_task(upscale_id) # upscale 本地合成，1–2s
single_image = final["image_urls"][0]

局部重绘（inpaint → modal 两步）：

imagine_id = submit({"prompt": "a portrait"})["data"][0]["task_id"]; wait_task(imagine_id)
upscale_id = submit_to("/upscale", {"task_id": imagine_id, "index": 1})["data"][0]["task_id"]; wait_task(upscale_id)

inpaint_id = submit_to("/inpaint", {"task_id": upscale_id})["data"][0]["task_id"] # status=modal
# 前端画 mask（透明=重绘区），上传到自己的 OSS 拿 mask_url
final = submit_to("/modal", {
 "task_id": inpaint_id,
 "prompt": "replace the eyes with cybernetic blue eyes",
 "mask_url": "https://your-oss.com/mask.png"
})
wait_task(final["data"][0]["task_id"])

⚠️ inpaint 进 MODAL 后 30 分钟内必须调 /modal，否则后台自动 CANCEL + 退款。

video 计费控制

  • 单段：batch_size: 1 → 扣 1 × midjourney@video
  • 批量 4 段：batch_size: 4 → 扣 4 × midjourney@video
  • 高清单段：video_type: "vid_1.1_i2v_720" + batch_size: 1 → 扣 1 × midjourney@video-720p

建议：出片只要 1 段就用 batch_size=1，批量比稿才用 4，不要默认开 4（成本翻 N 倍）。

并发与吞吐

import asyncio
sem = asyncio.Semaphore(10) # 客户端最多 10 个并发提交

async def submit_one(prompt):
 async with sem:
 return await submit({"prompt": prompt})
  • 平台对每分钟提交数有上限，超出返回 429，需退避重试。
  • 实际生成并发由系统容量决定，超出会排队；任务长时间停在 SUBMITTED 通常是排队中。
  • 轮询务必带 sleep，不要无 sleep 死循环。

监控建议

指标 参考阈值 含义
任务 SUCCESS 率（近 1h） > 95% 偏低说明服务 / 网络异常
平均完成耗时 \< 90s 偏高说明排队
MODAL 停留任务数 接近 0 偏多说明客户端没调 /modal
code=24 比例 \< 5% 偏高说明 prompt 频繁触发敏感词

排错清单

现象 排查方向
任务长时间 SUBMITTED 系统排队中，稍后再查
任务长时间 NOT_START 平台稍后会自动超时退款，无需手动处理
任务 MODAL 超 30 分钟 客户端没调 /modal，已被自动 CANCEL + 退款
prompt 字段为空 describe 任务的文字结果在 description 字段
image_urls 少一张 内容审核拦了部分图，看 fail_reason
计费超预期 看 quota 字段；video 记得 × batch_size

完整工作流示例

计费说明：按路径模型名计费（如 midjourney-imagine）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询推荐 GET /v1/midjourney/tasks/{task_id}（兼容 GET /v1/midjourney/{task_id}）。

imagine → upscale → inpaint → video 等端到端 curl 走查，附 bash / Python / TS 客户端封装

把多接口串起来的端到端示例。所有命令把 $KEY 换成你的 API token，$HOST 换成实际平台域名。

export KEY="sk-your-api-key"
export HOST="https://api.seedance.nz"

流程 A：基础文生图（imagine → upscale）

# 1. imagine 出 4 张图
curl -sS -X POST "$HOST/v1/midjourney/generations/imagine" \
 -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
 -d '{
 "prompt": "a futuristic city at sunset, photorealistic, cinematic lighting",
 "version": "8.1", "size": "16:9", "speed": "fast", "stylize": 250
 }'
# → {"code":200,"data":[{"task_id":"task_01KQVZAPBW...","status":"submitted"}]}

# 2. 轮询查询直到 SUCCESS（约 30–60s）
curl -sS "$HOST/v1/midjourney/task_01KQVZAPBW..." -H "Authorization: Bearer $KEY"
# → SUCCESS，含 grid_image_url + 4 张 image_urls + buttons(U1-U4 / V1-V4 / 🔄)

# 3. upscale 选第 2 张（本地合成，毫秒级 SUCCESS）
curl -sS -X POST "$HOST/v1/midjourney/generations/upscale" \
 -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
 -d '{"task_id": "task_01KQVZAPBW...", "index": 2}'
# → 查询拿单图 image_urls[0]

流程 B：垫图 → 强变体 → 放大

# 1. 垫图 imagine
curl -sS -X POST "$HOST/v1/midjourney/generations/imagine" \
 -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
 -d '{
 "prompt": "turn this product into a luxury studio photo",
 "image_urls": ["https://your-cdn.example.com/product.png"],
 "iw": 1.5, "size": "1:1"
 }'

# 2. 对结果做强变体
curl -sS -X POST "$HOST/v1/midjourney/generations/high-variation" \
 -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
 -d '{"task_id": "task_01XXX...", "index": 1, "speed": "fast"}'

# 3. 对变体的某张 upscale
curl -sS -X POST "$HOST/v1/midjourney/generations/upscale" \
 -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
 -d '{"task_id": "task_02_variant...", "index": 3}'

流程 C：局部重绘（inpaint + modal 两步）

前提：先 imagine + upscale 拿到单图任务（见流程 A）。

# 1. 提交 inpaint → 进 MODAL
curl -sS -X POST "$HOST/v1/midjourney/generations/inpaint" \
 -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
 -d '{"task_id": "task_02_upscaled..."}'
# → {"data":[{"task_id":"task_03_inpaint...","status":"modal"}]}
# 注意 status=modal，任务等你补 mask；30 分钟超时自动 CANCEL + 退款

# 2. 前端画 mask（透明=重绘区，白色=保留），上传到自己的 OSS 拿 mask_url（须公网可达）

# 3. 提交 modal 完成
curl -sS -X POST "$HOST/v1/midjourney/generations/modal" \
 -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
 -d '{
 "task_id": "task_03_inpaint...",
 "prompt": "replace the selected area with a red leather sofa",
 "mask_url": "https://your-oss.example.com/mask-abc.png"
 }'
# → 同 task_id，status 转 submitted；4. 轮询 60–90s 后 SUCCESS，含 4 张局部重绘候选

流程 D：扩图（Zoom Out）

# 直接出图，无需 mask（Outpaint / CustomZoom 都不进 MODAL）
curl -sS -X POST "$HOST/v1/midjourney/generations/zoom" \
 -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
 -d '{"task_id": "task_02_upscaled...", "zoom_ratio": 1.5, "speed": "fast"}'

流程 E：图生视频（i2v）

# 720p 高清 + batch=4（4 倍计费）
curl -sS -X POST "$HOST/v1/midjourney/generations/video" \
 -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
 -d '{
 "prompt": "city traffic at night, neon reflections, slow camera dolly",
 "image_urls": ["https://your-cdn.example.com/city.jpg"],
 "video_type": "vid_1.1_i2v_720", "batch_size": 4
 }'
# 实扣 = midjourney@video-720p × 4

# 起止帧 transition（end_url 自动升级为 start_end）
curl -sS -X POST "$HOST/v1/midjourney/generations/video" \
 -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
 -d '{
 "prompt": "transition smoothly from sunrise to sunset",
 "image_urls": ["https://your-cdn.example.com/sunrise.jpg"],
 "end_url": "https://your-cdn.example.com/sunset.jpg",
 "video_type": "vid_1.1_i2v_720"
 }'

通用工具：Python 客户端封装

import time
import httpx

API_KEY = "sk-..."
HOST = "https://api.seedance.nz"

class MjClient:
 def __init__(self):
 self.client = httpx.Client(
 base_url=HOST,
 headers={"Authorization": f"Bearer {API_KEY}"},
 timeout=30,
 )

 def imagine(self, prompt, **params):
 r = self.client.post("/v1/midjourney/generations/imagine",
 json={"prompt": prompt, **params})
 return r.json()["data"][0]["task_id"]

 def upscale(self, task_id, index):
 r = self.client.post("/v1/midjourney/generations/upscale",
 json={"task_id": task_id, "index": index})
 return r.json()["data"][0]["task_id"]

 def query(self, task_id):
 return self.client.get(f"/v1/midjourney/{task_id}").json()

 def wait(self, task_id, timeout=180):
 deadline = time.time() + timeout
 while time.time() < deadline:
 t = self.query(task_id)
 if t["status"] in ("SUCCESS", "FAILURE"):
 return t
 if t["status"] == "MODAL":
 raise RuntimeError(f"task {task_id} 需要调 /modal")
 time.sleep(3)
 raise TimeoutError(task_id)


mj = MjClient()
imagine_id = mj.imagine("a cat", version="8.1", speed="fast", size="16:9")
mj.wait(imagine_id)
upscale_id = mj.upscale(imagine_id, 2)
print(mj.wait(upscale_id)["image_urls"][0])

通用工具：TypeScript 封装

const API_KEY = "sk-...";
const HOST = "https://api.seedance.nz";

async function mj(path: string, body: any) {
 const r = await fetch(`${HOST}${path}`, {
 method: "POST",
 headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" },
 body: JSON.stringify(body),
 });
 return r.json();
}

async function query(id: string) {
 const r = await fetch(`${HOST}/v1/midjourney/${id}`, {
 headers: { "Authorization": `Bearer ${API_KEY}` },
 });
 return r.json();
}

async function waitTask(id: string, timeoutMs = 180_000) {
 const deadline = Date.now() + timeoutMs;
 while (Date.now() < deadline) {
 const t = await query(id);
 if (t.status === "SUCCESS" || t.status === "FAILURE") return t;
 if (t.status === "MODAL") throw new Error(`需要调 /modal: ${id}`);
 await new Promise((r) => setTimeout(r, 3000));
 }
 throw new Error(`超时: ${id}`);
}

const r = await mj("/v1/midjourney/generations/imagine",
 { prompt: "a cat", version: "8.1", speed: "fast" });
const result = await waitTask(r.data[0].task_id);
console.log(result.image_urls);

状态机

submit → NOT_START(0%) → SUBMITTED(5-30%) → IN_PROGRESS(~99%) → SUCCESS(100%)
 ↘ FAILURE(100%) → 自动退款
inpaint / CustomZoom → MODAL(15%) ──POST /modal {mask_url, prompt}──▶ SUBMITTED → ...
 └ 30min 超时 → CANCEL + 退款

创建自定义模型

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

使用 6–24 条参考音频创建可用于 Suno V6 生成的自定义模型

创建模型是异步任务。提交后先取得训练 task_id，轮询任务完成后再从 data.result.model_id 读取自定义模型 ID。

Authorizations

Bearer Token。登录 控制台 →「API 令牌」获取 API Key。

Body

固定使用 suno。 自定义模型名称。去掉首尾空白后不能为空。 6–24 条公网可访问的 HTTP(S) 音频直链，建议使用 MP3、WAV 或 M4A。每条 URL 都应直接返回音频文件，不能是需要登录的网页。 无效素材可能导致整个创建任务失败。本地文件请先使用项目的上传能力获得公网 URL；不要传本地路径或 blob: URL。

Response

响应状态码。提交结果。读取 data[0].task_id，再通过 GET /v1/music/tasks/{task_id} 查询训练状态。

使用创建的模型

完成后保存 result.model_id，后续在支持自定义模型的操作中作为 custom_model_id 使用，并省略 version 和 persona_id：

{
 "model": "suno",
 "custom_model_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
 "custom": true,
 "instrumental": false,
 "prompt": "[Verse]\n旧木吉他弹起新的旅程",
 "style": "acoustic folk, warm vocals",
 "max_mode": true,
 "audio_format": "mp3"
}

创建模型可能需要数分钟，最长约 20 分钟。自定义模型的实际可用时间可能变化，界面不应承诺固定的精确到期时间。创建模型与后续每次生成分别计费。

上传音频并翻唱

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

上传公网音频 URL，并使用 Suno V6 生成翻唱版本

本接口直接使用公开音频 URL 生成翻唱，无需先调用 uploadTask。提交后返回 task_id，通过 GET /v1/music/tasks/{task_id} 查询结果。

Authorizations

Bearer Token。登录 控制台 →「API 令牌」获取 API Key。

Body

固定使用 suno。 公网可访问的 HTTP(S) 音频直链，建议原音频不超过 8 分钟。本地路径、blob: URL 和需要登录的页面链接不可用。 公共版本：v6 / v6-wild / v6-mini。使用 custom_model_id 时省略。 创建模型任务返回的完整 UUID。与 version、persona_id 互斥。 建议显式发送。false 使用 gpt_description；true 使用歌词和风格字段。 是否生成纯音乐。custom=true 且本字段为 false 时，prompt 必填。 灵感描述，custom=false 时必填，不超过 3000 个字符。 自定义模式歌词，不超过 5000 个字符。 风格描述，不超过 1000 个字符。 标题，不超过 80 个字符。 不希望出现的风格。 风格权重，范围 0–1。 创意度权重，范围 0–1。 音频权重，范围 0–1。 是否对输入歌词进行二次创作。 人声性别：Male / Female。 Persona ID，与 custom_model_id 互斥。 目标生成时长，范围 10–360 秒，仅自定义模式可用。 风格变化程度：off / normal / high / extra / max。 是否启用 Max 模式。启用时要求自定义模式，并按普通售价的 2 倍计费。 输出格式：mp3 / m4a / wav。

Response

响应状态码。提交结果，读取 data[0].task_id 并轮询任务查询接口。

上传音频并延伸

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

上传公网音频 URL，并从指定位置使用 Suno V6 延伸歌曲

本接口直接延伸公开音频 URL，无需先调用 uploadTask。接口固定使用自定义模式，不要发送 custom、instrumental 或 gpt_description。

Authorizations

Bearer Token。登录 控制台 →「API 令牌」获取 API Key。

Body

固定使用 suno。公网可访问的 HTTP(S) 音频直链，建议不超过 8 分钟。本地路径与 blob: URL 不可用。 延伸起点，必须大于等于 1 秒，并严格小于源音频实际时长。 公共版本：v6 / v6-wild / v6-mini。使用 custom_model_id 时省略。 创建模型任务返回的完整 UUID。与 version、persona_id 互斥。 延伸段歌词，不超过 5000 个字符；省略时按纯音乐延伸语义使用。 风格描述，不超过 1000 个字符。标题，不超过 80 个字符。不希望出现的风格。风格权重，范围 0–1。创意度权重，范围 0–1。音频权重，范围 0–1。是否对输入歌词进行二次创作。人声性别：Male / Female。Persona ID，与 custom_model_id 互斥。目标生成时长，范围 10–360 秒。实际成品时长以任务结果为准。 风格变化程度：off / normal / high / extra / max。 是否启用 Max 模式；启用后按普通售价的 2 倍计费。 输出格式：mp3 / m4a / wav。## Response

响应状态码。提交结果，读取 data[0].task_id 并轮询任务查询接口。

Suno V6 通用约定与任务查询

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

Suno V6 的版本选择、自定义模型、异步任务生命周期、源音轨引用和结果结构

所有 Suno 生成、编辑和工具接口都采用异步任务：提交操作后取得 task_id，再通过本页接口查询结果。

认证

使用 Bearer Token 认证：Authorization: Bearer <你的 API Key>。 登录 控制台 →「API 令牌」获取 API Key。

V6 版本与模型选择

公共模型只支持以下版本：

  • v6
  • v6-wild
  • v6-mini

主生成接口必须提供 version，或提供创建模型任务返回的 custom_model_id。支持版本的编辑操作省略 version 时默认使用 v6。公共 version 与 custom_model_id 不能同时发送。

custom: true 表示自定义歌词模式，custom_model_id 表示使用已训练的自定义模型，两者不是同一个概念。使用自定义歌词模式不会自动切换到自定义模型价格档。

通用 V6 生成选项

仅在具体端点列出时发送以下字段：

字段 说明
variety 风格变化程度：off / normal / high / extra / max
max_mode Max 模式，默认 false；支持时按普通售价的 2 倍计费
audio_format 输出格式：mp3 / m4a / wav
duration / duration_s 目标生成时长，10–360 秒整数，仅指定生成操作支持

不支持某字段的操作应完全省略该字段；不要向所有操作统一发送 max_mode: false。variety 与 Max 模式相互独立，选择 variety: "max" 不会自动开启 Max 计费。

文本与权重限制

内容 字段 限制
灵感描述 prompt（主生成）/ gpt_description（操作接口） 不超过 3000 个字符
歌词 prompt（自定义模式） 不超过 5000 个字符
风格 style（主生成）/ tags（操作接口） 不超过 1000 个字符
标题 title 不超过 80 个字符
权重 style_weight / weirdness / audio_weight 0–1；数值 0 有效

操作接口的新请求使用 weirdness；weirdness_constraint 是兼容别名。主生成仍使用 weirdness_constraint。文本长度按 Unicode 字符数计算。

引用源音轨

基于已有作品的操作使用：

  • task_id：产出源音轨的 任务 ID。
  • audio_index：源任务查询响应的 data.result.music[] 中的原始位置，从 1 开始，默认 1。

返回多少首就按实际数组展示，不要把结果数量固定为 2。即使页面调整了展示顺序，后续操作仍须使用音轨在原始结果中的索引。

新请求统一使用 task_id + audio_index 引用源音轨，不能用 audio_id、music_id 或 audio_url 替代。无法解析源任务或索引越界时会返回 400。

提交响应

{
 "code": 200,
 "data": [
 {
 "status": "submitted",
 "task_id": "task_01M24YMN4EV04M84R5QYM77R1E"
 }
 ]
}

从 data[0].task_id 读取任务 ID。submitted 只表示任务已受理，不表示已有最终音频或其它产物。

查询任务

GET /v1/music/tasks/{task_id}

可附加 ?language=zh 获取适用的失败信息翻译。该参数不会改变歌曲或歌词语言。

提交接口返回的任务 ID。 建议首次等待约 3 秒，之后每 5–10 秒查询一次，直到 data.status 为 completed 或 failed。页面刷新后可继续使用同一个任务 ID 查询；不要因网络超时自动重发收费的 POST 请求。

查询响应

响应状态码。 任务信息。

本平台任务 ID。 pending / processing / completed / failed / unknown。 任务进度，通常为 0–100。是否完成应以 status 为准。 创建时间，Unix 秒。 预计耗时（秒），仅供参考，并非倒计时承诺。 任务金额（美元）。 任务消耗的积分值，请直接使用接口返回值展示。 完成后的结果，结构随操作不同。 失败信息，常见字段为 message / type / code / param。

结果处理

  • 音乐类结果通常位于 data.result.music[]，但下载、歌词、MIDI、Persona 和自定义模型等操作有各自的结果结构。
  • duration 是实际时长，允许小数；输入目标时长不保证与成品完全相同。
  • 权重返回值 0 是有效值，不能因为 JavaScript falsy 判断而隐藏。
  • audio_url 不保证使用 .mp3 后缀，请按接口返回的实际 URL 播放或下载。
  • status="unknown" 时保留任务 ID 并允许手动刷新，不要自动创建新任务。

AbortController 只能停止浏览器请求和轮询，不会取消服务器任务。当前接口没有取消已提交 Suno 任务的端点。

生成音乐

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 从提示词生成歌曲：custom=false 为灵感模式（prompt 作灵感提示词），=true 为自定义模式（prompt 作歌词）。
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

custom 决定文本字段是否生效：custom=true（自定义）时 prompt 作歌词，title、style、negative_tags、auto_lyrics 和 persona_id 生效；custom=false（灵感）时 prompt 作灵感描述，上述自定义字段被忽略。style_weight、weirdness_constraint、audio_weight 和 vocal_gender 在两种模式下都会校验并生效。 本端点的字段名与其他端点略有不同：使用 style，而不是 tags。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 false=灵感模式；true=自定义模式（prompt 作歌词）。默认 false。 true=纯音乐、无人声。默认 false。 公共版本：v6 / v6-wild / v6-mini。与 custom_model_id 至少提供一个；使用自定义模型时省略本字段。 创建自定义模型任务返回的完整 UUID。与 version、persona_id 互斥；提供本字段后按自定义模型价格档计费。 灵感提示词 / 歌词。custom=false 时必填且不超过 3000 个字符；custom=true 且 instrumental=false 时必填且不超过 5000 个字符；自定义纯音乐可省略。 标题（自定义模式），不超过 80 个字符。custom=false（灵感模式）时忽略。 风格标签（自定义模式），不超过 1000 个字符。custom=false（灵感模式）时忽略。 负向风格标签（不希望出现的风格）。仅 custom=true 时生效。 true=对输入歌词进行二次创作。仅 custom=true 时生效。 Persona 风格 ID。仅 custom=true 时生效，与 custom_model_id 互斥。 人声性别：Male / Female（也接受 m / f / male / female，后端自动归一）。两种模式均生效。 风格权重，0.00–1.00。两种模式下都会校验并生效。 创意度，0.00–1.00。两种模式下都会校验并生效。 音频权重，0.00–1.00。两种模式下都会校验并生效。 风格变化程度：off / normal / high / extra / max。可省略，没有固定默认值。 是否启用 Max 模式。启用时要求 custom=true，并按普通售价的 2 倍计费。 输出音频格式：mp3 / m4a / wav。省略时由服务自动选择。 目标生成时长，范围 10–360 秒，仅 custom=true 时可用。实际成品时长以任务结果为准。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（音乐生成通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后在 data.result.music[] 取 audio_url（另有 image_url / video_url / title / duration 等）。失败时 data.error.message 为原因，自动退回预扣额度。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

生成歌词

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 根据主题生成歌词文本。
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

本端点无版本维度：不要传 version，传了会被丢弃，也不影响计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 想生成什么歌词的描述，去掉首尾空白后不能为空。 歌词模型：classic / remi。不传时使用服务默认设置。 获取结果：提交后轮询 GET /v1/music/tasks/{task_id}。优先读取 result.lyrics[] 中的 text、title 和 tags；同时兼容 result.text、字符串形式的 result.lyrics 以及历史数组结构。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

续写延长

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 在已有歌曲的某个时间点之后续写延长。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 extend 的 custom 为可选参数，省略时默认 true。custom=true 时按 prompt（歌词）续写；只有显式传入 custom=false 时，才使用 gpt_description（灵感描述）引导续写方向。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id；缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 从第几秒开始续写，必须大于等于 1 且小于源音轨实际时长。支持小数秒。 公共版本：v6 / v6-wild / v6-mini；省略时默认 v6。使用 custom_model_id 时省略本字段。 创建模型任务返回的完整 UUID。与 version、persona_id 互斥。 true=按 prompt 歌词续写；false=灵感续写。省略时默认 true。 续写歌词，custom=true 时生效。 灵感提示词，仅在显式传入 custom=false 时生效，用于引导续写方向。 标题。仅 custom=true 时生效。 风格标签。仅 custom=true 时生效。 排除的风格标签。仅 custom=true 时生效。 人声性别：Male / Female。两种模式均生效。 风格权重，0.00–1.00（超出范围提交期直接返回 400）。仅 custom=true 时生效。 创意度权重，0.00–1.00。兼容旧名 weirdness_constraint；新请求请使用 weirdness。 音频权重，0.00–1.00。仅 custom=true 时生效。 true=对输入歌词进行二次创作。仅 custom=true 时生效。 Persona 风格 ID。仅 custom=true 时生效，与 custom_model_id 互斥。 目标生成时长，范围 10–360 秒，仅 custom=true 时可用。实际时长以结果为准。 风格变化程度：off / normal / high / extra / max。可省略。 是否启用 Max 模式。启用时要求 custom=true，并按普通售价的 2 倍计费。 输出音频格式：mp3 / m4a / wav。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（音乐生成通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后在 data.result.music[] 取延长后的 audio_url。失败时 data.error.message 为原因，自动退回预扣额度。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

上传音频

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 把一段公网音频导入，得到可供后续（翻唱 / 续写等）引用的音轨；完成后本任务 task_id 即可作源（audio_index=1）。
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

本端点只接收 JSON，不上传二进制文件。请先上传音频并获得公网 URL，再将其填入 audioFilePath。不要发送 version、audio_format 或本文未列出的参数。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

已上传到对象存储、可公开读取的音频 HTTP(S) 直链。本机路径与 blob: URL 不可用。 获取结果：本接口为异步任务。提交后拿到 task_id，轮询 GET /v1/music/tasks/{task_id}。完成后使用本任务 task_id + audio_index=1 作为其它操作的源；上传结果可能只有 audio_id，不保证返回可播放的 audio_url。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

风格翻唱

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 以另一种风格翻唱已有歌曲。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 custom 决定字段是否生效；无论字段是否在当前模式生效，已提交字段仍须满足类型、范围和长度要求。custom=true 时 prompt（歌词）、title、tags、negative_tags、style_weight、weirdness、audio_weight、persona_id 生效，gpt_description 被忽略；custom=false 时只认 gpt_description（此时必填，缺了提交期直接 400）。vocal_gender 两种模式都生效。不传 custom 时后端按此顺序推断：有 prompt → true；无 prompt 但有 gpt_description → false；否则有 tags/title → true。

用法

用法 A —— 指定风格翻唱（最常用，推荐）

给源歌曲 + 目标风格 tags，不用管 custom（系统看到 tags 会自动按 custom=true 处理）：

{
 "model": "suno",
 "task_id": "task_xxx", // 源歌曲：一个已完成的音乐任务
 "audio_index": 1, // 源任务里第几首（1-based，默认 1）
 "version": "v6",
 "tags": "jazz, slow" // 目标风格 → 自动 custom=true
}

想更精确可以再加 prompt（歌词）/ title。

用法 B —— 灵感模式（custom=false）

不指定具体风格，让模型自己发挥，但必须给 gpt_description 描述你想要的效果：

{
 "model": "suno",
 "task_id": "task_xxx",
 "audio_index": 1,
 "version": "v6",
 "custom": false,
 "gpt_description": "把这首歌翻唱成慢速爵士风格" // custom=false 时必填
}

两种用法二选一，别只传 custom=false 却不给 gpt_description（会提交期直接 400）。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id；缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based：1=第 1 首；默认 1；一次生成通常 2 首：索引 1 与 2）。 公共版本：v6 / v6-wild / v6-mini；省略时默认 v6。使用 custom_model_id 时省略本字段。 创建模型任务返回的完整 UUID。与 version、persona_id 互斥。 true=自定义模式（用 prompt 作歌词）；false=灵感模式（用 gpt_description）；不传时按内容推断（见上方 Warning）。 歌词，custom=true 时生效（灵感模式下会被忽略）。 灵感提示词，custom=false 时必填（缺了提交期直接 400、不扣费）。 标题。仅 custom=true 时生效。 目标风格标签。仅 custom=true 时生效。 排除的风格标签。仅 custom=true 时生效。 风格权重，0.00–1.00（超出范围提交期直接返回 400）。仅 custom=true 时生效。 创意度权重，0.00–1.00。兼容旧名 weirdness_constraint；新请求请使用 weirdness。 音频权重，0.00–1.00。仅 custom=true 时生效。 人声性别：Male / Female。两种模式均生效。 Persona 风格 ID。仅 custom=true 时生效，与 custom_model_id 互斥。 目标生成时长，范围 10–360 秒，仅 custom=true 时可用。实际时长以结果为准。 风格变化程度：off / normal / high / extra / max。可省略。 是否启用 Max 模式。启用时要求自定义模式，并按普通售价的 2 倍计费。 输出音频格式：mp3 / m4a / wav。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（音乐生成通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后在 data.result.music[] 取 audio_url。失败时 data.error.message 为原因，自动退回预扣额度。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

完整歌曲合成 / 拼接

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 把片段合成为完整歌曲。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 本端点无版本维度：不要传 version——传了会被丢弃、也不影响计费。 前提：concat 只能拼接 extend（续写）产生的分段结果。若源不是 extend 产物（如普通一次性生成的整首歌），提交期直接返回 400。 歌曲合成本身免费。生成前置续写片段所调用的 extend 接口会按其价格单独计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 源任务的 task_id——必须是 extend（续写）产生的分段（见上方 Warning）。缺失、非 extend 产物或无法解析源时，提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 输出音频格式：mp3 / m4a / wav。 源任务必须是 extend 或 extendMusic 的续写结果。本接口用于合成一条续写链，不是任意两首歌曲的拼接工具。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后从 data.result.music[] 取完整歌曲 audio_url。失败时 data.error.message 给出原因，且预扣额度自动退回。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

分轨提取

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 从歌曲分离出指定轨（如人声）。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 本端点无版本维度：不要传 version，传了会被丢弃，也不影响计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id；缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 要提取的分轨类型。省略时默认使用 lead_vocal。常用值包括 lead_vocal、backing_vocals、drum_kit、bass、piano 和 electric_guitar。

lead_vocal drum_kit bass backing_vocals piano electric_guitar percussion
string_section synth acoustic_guitar sound_effects synth_pad synth_bass
guitar brass_section organ electronic_drum_kit lead_electric_guitar synth_keys
rhythm_electric_guitar electric_piano upright_bass keyboards distorted_electric_guitar
kick snare risers synth_strings synth_lead woodwinds flute harp tambourine trumpet
arpeggiator accordion fiddle pedal_steel_guitar synth_voice violin digital_piano
synth_brass mandolin choir banjo bells clarinet tenor_saxophone trombone shaker
french_horn glockenspiel electric_bass cello timpani harmonica marimba vibraphone
lap_steel_guitar saxophone orchestra horns cymbals hand_clap oboe celesta congas
drone alto_saxophone double_bass ukulele harpsichord baritone_saxophone xylophone
tuba bass_guitar whistle lead_guitar rhodes 808 bongos bassoon cowbell viola sitar
steel_drums piccolo theremin bagpipes hi_hat music_box melodica tabla koto djembe
taiko didgeridoo

808 必须作为字符串发送，例如 "stem_type": "808"。 输出音频格式：mp3 / m4a / wav。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后结果里含分离出的轨 URL。失败时 data.error.message 为原因，自动退回预扣额度。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

全量分轨

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 多轨全分离。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 本端点无版本维度：不要传 version，传了会被丢弃，也不影响计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id；缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 输出音频格式：mp3 / m4a / wav。本接口不发送 stem_type、version 或 Max 字段。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后结果里含各分轨 URL。失败时 data.error.message 为原因，自动退回预扣额度。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

添加人声

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 给现有（伴奏 / 音轨）叠加人声。
  • 使用 task_id + audio_index 引用 uploadTask 上传任务中的音轨
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：源音轨必须来自 POST /v1/music/generations/upload 创建的上传任务。传入该任务的 task_id，并用 audio_index 指定 data.result.music[] 中的音轨（1-based，默认 1）。普通生成任务不能作为本接口的源任务。 custom 决定字段是否生效；无论字段是否在当前模式生效，已提交字段仍须满足类型、范围和长度要求。custom=true 时 prompt（歌词）、title、tags、negative_tags、style_weight、weirdness、audio_weight 生效，gpt_description 被忽略；custom=false 时只认 gpt_description（此时必填，缺了提交期直接 400）。vocal_gender 两种模式都生效。不传 custom 时后端按此顺序推断：有 prompt → true；无 prompt 但有 gpt_description → false；否则有 tags/title → true。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 POST /v1/music/generations/upload 返回的上传任务 ID。普通生成任务不能使用；缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 公共版本：v6 / v6-wild / v6-mini；省略时默认 v6。使用 custom_model_id 时省略本字段。 创建模型任务返回的完整 UUID，与 version 互斥。 true=自定义模式（用 prompt 作歌词）；false=灵感模式（用 gpt_description）；不传时按内容推断（见上方 Warning）。 歌词，custom=true 时生效（灵感模式下会被忽略）。 灵感提示词，custom=false 时必填（缺了提交期直接 400、不扣费）。 标题。仅 custom=true 时生效。 风格标签。仅 custom=true 时生效。 排除的风格标签。仅 custom=true 时生效。 风格权重，0.00–1.00（超出范围提交期直接返回 400）。仅 custom=true 时生效。 创意度权重，0.00–1.00。兼容旧名 weirdness_constraint；新请求请使用 weirdness。 音频权重，0.00–1.00。仅 custom=true 时生效。 人声性别：Male / Female。两种模式均生效。 风格变化程度：off / normal / high / extra / max。 是否启用 Max 模式。启用时要求自定义模式，并按普通售价的 2 倍计费。 输出音频格式：mp3 / m4a / wav。本接口不支持目标时长字段。 本接口不支持 auto_lyrics、persona_id、instrumental 或目标时长字段。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（音乐生成通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后在 data.result.music[] 取 audio_url。失败时 data.error.message 为原因，自动退回预扣额度。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

添加伴奏

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 给现有（人声 / 音轨）叠加伴奏。
  • 使用 task_id + audio_index 引用 uploadTask 上传任务中的音轨
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：源音轨必须来自 POST /v1/music/generations/upload 创建的上传任务。传入该任务的 task_id，并用 audio_index 指定 data.result.music[] 中的音轨（1-based，默认 1）。普通生成任务不能作为本接口的源任务。 custom 决定哪些字段生效；无论字段是否在当前模式生效，已提交字段仍须满足类型、范围和长度要求。custom=true 时 prompt（歌词）、title、tags、negative_tags、style_weight、weirdness、audio_weight 生效，gpt_description 被忽略；custom=false 时只读 gpt_description（此时必填，缺了提交期直接返回 400）。vocal_gender 两种模式都生效。不传 custom 时后端按此顺序推断：有 prompt → true；无 prompt 但有 gpt_description → false；否则有 tags/title → true。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 POST /v1/music/generations/upload 返回的上传任务 ID。普通生成任务不能使用；缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 公共版本：v6 / v6-wild / v6-mini；省略时默认 v6。使用 custom_model_id 时省略本字段。 创建模型任务返回的完整 UUID，与 version 互斥。 true=自定义模式（用 prompt 作歌词）；false=灵感模式（用 gpt_description）；不传时按内容推断（见上方 Warning）。 歌词，custom=true 时生效（灵感模式下会被忽略）。 灵感提示词，custom=false 时必填（缺了提交期直接 400、不扣费）。 标题。仅 custom=true 时生效。 风格标签。仅 custom=true 时生效。 要排除的风格标签。仅 custom=true 时生效。 风格权重，0.00–1.00（越界提交期直接返回 400）。仅 custom=true 时生效。 创意权重，0.00–1.00。兼容旧名 weirdness_constraint；新请求请使用 weirdness。 音频权重，0.00–1.00。仅 custom=true 时生效。 人声性别：Male / Female。两种模式都生效。 风格变化程度：off / normal / high / extra / max。 是否启用 Max 模式。启用时要求自定义模式，并按普通售价的 2 倍计费。 输出音频格式：mp3 / m4a / wav。本接口不支持目标时长字段。 本接口不支持 auto_lyrics、persona_id、instrumental 或目标时长字段。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（音乐生成通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后从 data.result.music[] 取 audio_url。失败时 data.error.message 给出原因，且预扣额度自动退回。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

添加音轨 (add stem)

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 在现有音轨上叠加一条 stem。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 custom 决定哪些字段生效；无论字段是否在当前模式生效，已提交字段仍须满足类型、范围和长度要求。custom=true 时 prompt（歌词）、title、tags、negative_tags、style_weight、weirdness、audio_weight 生效，gpt_description 被忽略；custom=false 时只读 gpt_description（此时必填，缺了提交期直接返回 400）。不传 custom 时后端按此顺序推断：有 prompt → true；无 prompt 但有 gpt_description → false；否则有 tags/title → true。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id。缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 公共版本：v6 / v6-wild / v6-mini；省略时默认 v6。使用 custom_model_id 时省略本字段。 创建模型任务返回的完整 UUID，与 version 互斥。 true=自定义模式（用 prompt 作歌词）；false=灵感模式（用 gpt_description）；不传时按内容推断（见上方 Warning）。 歌词，custom=true 时生效（灵感模式下会被忽略）。 灵感提示词，custom=false 时必填（缺了提交期直接 400、不扣费）。 标题。仅 custom=true 时生效。 风格标签。仅 custom=true 时生效。 要排除的风格标签。仅 custom=true 时生效。 风格权重，0.00–1.00（越界提交期直接返回 400）。仅 custom=true 时生效。 创意权重，0.00–1.00。兼容旧名 weirdness_constraint；新请求请使用 weirdness。 音频权重，0.00–1.00。仅 custom=true 时生效。 风格变化程度：off / normal / high / extra / max。 是否启用 Max 模式。启用时要求自定义模式，并按普通售价的 2 倍计费。 输出音频格式：mp3 / m4a / wav。本接口不支持目标时长字段。 本接口不支持 auto_lyrics、persona_id、instrumental、vocal_gender 或目标时长字段。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（音乐生成通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后从 data.result.music[] 取 audio_url。失败时 data.error.message 给出原因，且预扣额度自动退回。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

段落替换

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 替换歌曲的某一段（infill）。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id。缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 替换段歌词。 替换起点（秒）。缺失直接返回 400。 替换终点（秒）。必须满足 0 ≤ start_s < end_s；源时长已知时不能越界。 公共版本：v6 / v6-wild / v6-mini；省略时默认 v6。使用 custom_model_id 时省略本字段。 创建模型任务返回的完整 UUID，与 version 互斥。 上下文歌词。 标题。 风格标签。 要排除的风格标签。 风格变化程度：off / normal / high / extra / max。可省略。 是否启用 Max 模式；启用后按普通售价的 2 倍计费。 输出音频格式：mp3 / m4a / wav。本接口不支持目标时长字段。 prompt 是原歌词上下文，infill_lyrics 是替换片段的新歌词。不要发送 custom、instrumental、auto_lyrics 或旧编辑会话字段。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（音乐生成通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后从 data.result.music[] 取替换后的 audio_url。失败时 data.error.message 给出原因，且预扣额度自动退回。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

删除片段

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 删除歌曲的某个时间区间。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 本端点无版本维度：不要传 version——传了会被丢弃、也不影响计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id。缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 删除起点（秒），必须大于等于 0；支持小数秒。 删除终点（秒）。必须大于 start_s，且不能超过已知源时长；支持小数秒。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后从 data.result.music[] 取处理后的 audio_url。失败时 data.error.message 给出原因，且预扣额度自动退回。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

裁剪音频

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 裁剪保留指定区间。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 本端点无版本维度：不要传 version——传了会被丢弃、也不影响计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id。缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 裁剪起点（秒），必须大于等于 0；支持小数秒。 裁剪终点（秒）。必须大于 start_s，且不能超过已知源时长；支持小数秒。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后从 data.result.music[] 取裁剪后的 audio_url。失败时 data.error.message 给出原因，且预扣额度自动退回。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

淡入

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 开头淡入。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 本端点无版本维度：不要传 version——传了会被丢弃、也不影响计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id。缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 淡入时长（秒）。必须大于 0，且不能超过已知源时长；支持小数秒。 标题（默认 Untitled）。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后从 data.result.music[] 取处理后的 audio_url。失败时 data.error.message 给出原因，且预扣额度自动退回。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

淡出

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 结尾淡出。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 本端点无版本维度：不要传 version——传了会被丢弃、也不影响计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id。缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 淡出时长（秒）。必须大于 0，且不能超过已知源时长；支持小数秒。 标题（默认 Untitled）。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后从 data.result.music[] 取处理后的 audio_url。失败时 data.error.message 给出原因，且预扣额度自动退回。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

调整速度

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 变速（不改音高）。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 本端点无版本维度：不要传 version——传了会被丢弃、也不影响计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id。缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 倍速，范围 0.25～4，如 1.25。缺失或越界提交期直接返回 400。 变速时是否保持原音高（默认 true）。 标题（默认 Untitled）。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后从 data.result.music[] 取处理后的 audio_url。失败时 data.error.message 给出原因，且预扣额度自动退回。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

母带优化

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 对已生成歌曲做母带优化，提升音质、清晰度与整体质感。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 本端点没有版本参数，请勿传入 version。任务按 suno@remaster 计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id；缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 改编强度：subtle / normal / high。 输出音频格式：mp3 / m4a / wav。 本接口不支持 custom_model_id、max_mode、variety 或目标时长字段。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（音乐生成通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后在 data.result.music[] 取优化后的 audio_url。失败时 data.error.message 为原因，自动退回预扣额度。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

生成音乐视频 (MV)

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 为歌曲生成 MV 视频。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 本端点无版本维度：不要传 version——传了会被丢弃、也不影响计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id。缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 获取结果：提交后轮询 GET /v1/music/tasks/{task_id}。完成后优先读取 data.result.videoUrl，并兼容历史 result.videos[] 或 result.music[].video_url。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

下载音频文件

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 将 Suno 歌曲下载为 MP3、M4A 或 WAV 文件
  • 支持一次请求多个格式，返回对应的文件 URL
  • 使用源任务 task_id 和 audio_index 指定要下载的歌曲
  • 异步提交任务，通过音乐任务查询接口获取结果

原 POST /v1/music/generations/wav 接口已弃用。旧接口暂时兼容，等价于调用新接口并传入 formats: ["wav"]；新代码请统一使用 POST /v1/music/generations/download。 指定源歌曲： 传入生成源音轨时获得的 task_id，并用 audio_index 指定结果 data.result.music[] 中的第几首歌曲。audio_index 从 1 开始，默认值为 1。

认证

所有接口均使用 Bearer Token 认证。登录 控制台 →「API 令牌」获取 API Key。

Authorization: Bearer YOUR_API_KEY

请求参数

模型名称。当前填写 suno；省略时默认为 suno。 生成源歌曲时返回的任务 ID。

源任务必须：

  • 属于当前账户
  • 已完成
  • 包含可下载的音轨

音乐生成、延长、翻唱、分轨等音频任务均可作为来源；歌词、BPM 等仅返回文本的任务无法下载。 要下载源任务结果 data.result.music[] 中的第几首歌曲。

  • 从 1 开始计数
  • 默认：1
  • 不得超过源任务实际包含的歌曲数量 要下载的文件格式数组，至少包含一项。

可选值：

  • mp3
  • m4a
  • wav

支持同时请求多个格式；格式名大小写不敏感，重复值会自动去重。结果顺序与请求顺序一致。 只下载一种格式时，可使用此字段代替 formats。

示例："format": "mp3" formats 和 format 选择一种写法即可。两者均未提供或格式列表为空时，请求会返回 HTTP 400。

提交响应

成功提交后返回下载任务自己的 task_id：

{
 "code": 200,
 "data": [
 {
 "status": "submitted",
 "task_id": "task_01JHXXXXXXXXXXXX"
 }
 ]
}

返回的 data 是数组，请读取 data[0].task_id。它是新建的下载任务 ID，与请求中的源歌曲 task_id 不同。

查询下载结果

使用提交响应中的下载任务 ID 查询：

GET /v1/music/tasks/{task_id}

文件通常已在提交阶段准备完成，因此提交后可以立即查询一次。如果状态不是 completed 或 failed，再每 2 秒轮询一次，最多等待 60 秒。

下载完成

{
 "code": 200,
 "data": {
 "id": "task_01JHXXXXXXXXXXXX",
 "status": "completed",
 "progress": 100,
 "created": 1756800000,
 "completed": 1756800003,
 "actual_time": 3,
 "cost": 0.01,
 "credits_cost": 0.1,
 "result": {
 "music_id": "518c74ee-62ac-4ccd-b3d9-7003acd12ad7",
 "files": [
 {
 "format": "mp3",
 "url": "https://assets.api.seedance.nz/audio/example.mp3"
 },
 {
 "format": "wav",
 "url": "https://assets.api.seedance.nz/audio/example.wav"
 }
 ],
 "wavUrl": "https://assets.api.seedance.nz/audio/example.wav"
 }
 }
}

读取 result.files[] 获取下载文件：

字段 类型 说明
format string 文件格式：mp3 / m4a / wav
url string 文件下载地址

result.wavUrl 仅用于兼容旧 WAV 接口。新代码请统一读取 result.files[]。

处理中

{
 "code": 200,
 "data": {
 "id": "task_01JHXXXXXXXXXXXX",
 "status": "processing",
 "progress": 50,
 "created": 1756800000
 }
}

此时没有 result 字段，请继续轮询。

下载失败

{
 "code": 200,
 "data": {
 "id": "task_01JHXXXXXXXXXXXX",
 "status": "failed",
 "progress": 100,
 "cost": 0,
 "error": {
 "message": "文件处理失败"
 }
 }
}

失败任务会自动退款，cost 为 0。可向用户显示 error.message 并提供重试操作。

文件 URL

下载结果通常使用 文件域名。返回的文件 URL 可能存在有效期，请在任务完成后及时下载并保存。

请在获得 URL 后尽快下载并保存文件，不要将临时 URL 作为长期存储地址。

错误处理

提交期参数错误会返回 HTTP 400，不创建任务、不扣费：

错误信息 原因
formats is required / must contain at least one 未提供下载格式
unsupported format 包含 mp3 / m4a / wav 以外的格式
task_id is required / invalid task_id format 源任务 ID 缺失或格式错误
source task not found 源任务不存在或不属于当前账户
audio_index N out of range 歌曲序号超出源任务音轨数量
track #N has no music_id 源任务未完成或对应歌曲没有音频

HTTP 403 且错误码为 model_price_not_configured 时，表示后台未配置 suno@download 价格，请联系平台支持。

计费与重复下载

下载接口按请求计费：

  • 一次请求选择多个格式只收取一次费用
  • 再次提交同一首歌曲，即使格式相同，也会产生新费用
  • 下载另一种格式需要新建任务，也会产生新费用
  • 下载失败会自动退款

请保存已返回的文件 URL，并在请求处理中禁用下载按钮，避免重复提交和重复扣费。

从旧接口迁移

项目 旧接口 新接口
请求路径 /v1/music/generations/wav /v1/music/generations/download
格式 仅 WAV MP3 / M4A / WAV，可多选
新增参数 — formats 或 format
结果字段 result.wavUrl result.files[]
兼容字段 result.wavUrl 请求 WAV 时仍可能返回 result.wavUrl

旧接口仍可暂时使用，但新功能和新代码应切换到 /generations/download。

Response

响应状态码，成功时为 200 提交响应数据。

初始状态为 submitted 下载任务 ID，用于轮询 GET /v1/music/tasks/{task_id}

生成 MIDI

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 从歌曲生成 MIDI。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 本端点无版本维度：不要传 version——传了会被丢弃、也不影响计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id。缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 获取结果：提交后轮询 GET /v1/music/tasks/{task_id}。完成结果通常包含 result.state 和 result.instruments[]，每个乐器的 notes[] 提供音符数据；当前不保证直接返回 .mid 文件 URL。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

BPM 分析

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 分析歌曲 BPM。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 本端点无版本维度：不要传 version——传了会被丢弃、也不影响计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id。缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 获取结果：提交后轮询 GET /v1/music/tasks/{task_id}。完成后读取 result.avg_bpm、result.min_bpm 和 result.max_bpm；字段可能为字符串或数字，转换后应检查是否为有限数值。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

歌词时间轴

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 生成逐句对齐的歌词时间轴。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 本端点无版本维度：不要传 version——传了会被丢弃、也不影响计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id。缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 获取结果：提交后轮询 GET /v1/music/tasks/{task_id}。优先读取 result.alignment[] 与 result.waveform_data；历史任务也可能在 music[] 中返回 aligned_words、aligned_lyrics 或 waveform_data。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

标签增强

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 优化 / 扩写风格标签，提升 prompt 质量。
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果。

本端点无版本维度：不要传 version，传了会被丢弃，也不影响计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 待增强的风格标签；缺失时提交期直接返回 400（不扣费）。 获取结果：提交后读取 data[0].task_id，再查询 GET /v1/music/tasks/{task_id}。完成后从 data.result.upsampled_tags 读取优化后的标签。无论任务多快完成，都需要通过任务查询接口获取结果。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

音效生成

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 根据描述生成音效。
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 公共版本：v6 / v6-wild / v6-mini；省略时默认 v6。 音效文本描述；缺失时提交期直接返回 400（不扣费）。建议尽量使用英文提示词，效果更佳。 音效类型：one-shot（默认，单次）/ loop（可循环）。 速度，1–300；超出范围提交期直接返回 400。 调性枚举：大调 C / C# / D / D# / E / F / F# / G / G# / A / A# / B；小调在后面加 m（Cm / C#m / … / Bm）。仅支持升号（#）写法，降号（Db / Eb 等）与 B# 会返回 400（key param error）。 输出音频格式：mp3 / m4a / wav。 本接口不支持自定义模型、Max、variety 或目标时长字段。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后在 data.result.music[] 取 audio_url。失败时 data.error.message 为原因，自动退回预扣额度。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

灵感生成 (inspo)

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 用 1–4 段公网音频作为灵感参考生成新歌（直接给音频 URL，不走 task_id）。
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 1–4 个可公开访问的音频 URL 数组。 公共版本：v6 / v6-wild / v6-mini；省略时默认 v6。使用 custom_model_id 时省略本字段。 创建模型任务返回的完整 UUID，与 version 互斥。 歌词 / 内容。 标题。 风格标签。 排除的风格标签。 风格权重，0.00–1.00。 创意度权重，0.00–1.00。兼容旧名 weirdness_constraint；新请求请使用 weirdness。 音频权重，0.00–1.00。 人声性别：Male / Female。 true=对输入歌词进行二次创作。 风格变化程度：off / normal / high / extra / max。可省略。 是否启用 Max 模式；启用后按普通售价的 2 倍计费。 输出音频格式：mp3 / m4a / wav。 本接口接收 1–4 条公开音频直链，不发送 custom、instrumental、gpt_description、persona_id 或目标时长字段。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（音乐生成通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后在 data.result.music[] 取 audio_url。失败时 data.error.message 为原因，自动退回预扣额度。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

样本转歌曲 (sample)

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 以样本为基础生成歌曲。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 custom 决定哪些字段生效；无论字段是否在当前模式生效，已提交字段仍须满足类型、范围和长度要求。custom=true 时 prompt（歌词）、title、tags、negative_tags、auto_lyrics、style_weight、weirdness、audio_weight 生效，gpt_description 被忽略；custom=false 时只读 gpt_description（此时必填，缺了提交期直接返回 400）。vocal_gender 两种模式都生效。不传 custom 时后端按此顺序推断：有 prompt → true；无 prompt 但有 gpt_description → false；否则有 tags/title → true。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id，必须为 uploadTask 上传任务。缺失、不是上传任务或无法解析源时，提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based：1=第 1 首；默认 1；一次生成通常 2 首：索引 1 与 2）。 采样起点（秒）。缺失直接返回 400。 采样终点（秒）。必须满足 0 ≤ start_s < end_s；源时长已知时不能越界。 是否纯器乐（true=无人声）；不传默认 false（要人声）。 公共版本：v6 / v6-wild / v6-mini；省略时默认 v6。使用 custom_model_id 时省略本字段。 创建模型任务返回的完整 UUID，与 version 互斥。 true=自定义模式（用 prompt 作歌词）；false=灵感模式（用 gpt_description）；不传时按内容推断（见上方 Warning）。 条件必填：custom=true && instrumental=false 时必须提供歌词；灵感模式下不生效，但已提交值仍须满足长度要求。 灵感提示词，custom=false 时必填（缺了提交期直接 400、不扣费）。 标题。仅 custom=true 时生效。 风格标签。仅 custom=true 时生效。 要排除的风格标签。仅 custom=true 时生效。 true=对输入歌词进行二次创作。仅 custom=true 时生效。 风格权重，0.00–1.00（越界提交期直接返回 400）。仅 custom=true 时生效。 创意权重，0.00–1.00。兼容旧名 weirdness_constraint；新请求请使用 weirdness。 音频权重，0.00–1.00。仅 custom=true 时生效。 人声性别：Male / Female。两种模式都生效。 风格变化程度：off / normal / high / extra / max。可省略。 是否启用 Max 模式。启用时要求自定义模式，并按普通售价的 2 倍计费。 输出音频格式：mp3 / m4a / wav。本接口不支持目标时长字段。 源任务必须来自 uploadTask 上传结果；start_s 与 end_s 都是必填值，不会自动补成 0 或 60。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（音乐生成通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后从 data.result.music[] 取 audio_url。失败时 data.error.message 给出原因，且预扣额度自动退回。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

生成混搭 (mashup)

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 把歌曲做混搭再创作。
  • 引用源音轨：需恰好 2 个，用 task_ids（长度 2 的数组）+ 可选 audio_indexes 指定
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：mashup 需要恰好 2 个源音轨——用 task_ids（长度为 2 的 task_id 数组）指定，可选 audio_indexes（与之平行的数组，指定各任务取 music[] 第几首，1-based，默认都取 1）。 custom 决定哪些字段生效；无论字段是否在当前模式生效，已提交字段仍须满足类型、范围和长度要求。custom=true 时 prompt（歌词）、title、tags、negative_tags、auto_lyrics、style_weight、weirdness、audio_weight、persona_id 生效，gpt_description 被忽略；custom=false 时只读 gpt_description（此时必填，缺了提交期直接返回 400）。vocal_gender 两种模式都生效。不传 custom 时后端按此顺序推断：有 prompt → true；无 prompt 但有 gpt_description → false；否则有 tags/title → true。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 2 个源音轨所属任务的 task_id 数组（须恰好 2 个；数量不对提交期直接返回 400）。 与 task_ids 平行的数组，指定各任务取结果 data.result.music[] 第几首（1-based，默认都取 1）。 是否纯器乐（true=无人声）；不传默认 false（要人声）。 公共版本：v6 / v6-wild / v6-mini；省略时默认 v6。使用 custom_model_id 时省略本字段。 创建模型任务返回的完整 UUID。与 version、persona_id 互斥。 true=自定义模式（用 prompt 作歌词）；false=灵感模式（用 gpt_description）；不传时按内容推断（见上方 Warning）。 条件必填：custom=true && instrumental=false 时必须提供歌词；灵感模式下不生效，但已提交值仍须满足长度要求。 灵感提示词，custom=false 时必填（缺了提交期直接 400、不扣费）。 标题。仅 custom=true 时生效。 风格标签。仅 custom=true 时生效。 要排除的风格标签。仅 custom=true 时生效。 true=对输入歌词进行二次创作。仅 custom=true 时生效。 风格权重，0.00–1.00（越界提交期直接返回 400）。仅 custom=true 时生效。 创意权重，0.00–1.00。兼容旧名 weirdness_constraint；新请求请使用 weirdness。 音频权重，0.00–1.00。仅 custom=true 时生效。 人声性别：Male / Female。两种模式都生效。 Persona 风格 ID。仅 custom=true 时生效，与 custom_model_id 互斥。 风格变化程度：off / normal / high / extra / max。可省略。 是否启用 Max 模式。启用时要求自定义模式，并按普通售价的 2 倍计费。 输出音频格式：mp3 / m4a / wav。本接口不支持目标时长字段。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（音乐生成通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。完成后从 data.result.music[] 取 audio_url。失败时 data.error.message 给出原因，且预扣额度自动退回。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

创建语音

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 从音轨创建可复用音色。
  • 引用源音轨：本端点不走 task_id + audio_index，直接给一个可公开访问的 audio_url
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：本端点不走 task_id + audio_index，需直接给一个可公开访问的 audio_url（系统据此提取音色）。缺失会返回 400 audio_url cannot be empty。 本端点无版本维度：不要传 version——传了会被丢弃、也不影响计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 源音轨的公网可访问 URL，系统据此提取音色。仅接受 MP3 / WAV。 缺失返回 400 audio_url cannot be empty。 获取结果：本接口为异步任务。提交后拿到 task_id，轮询 GET /v1/music/tasks/{task_id}。当前没有固定的 result.voice_id 响应约定，请按实际返回对象展示，不要把结果直接当作 persona_id 使用。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

Persona

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 基于已有歌曲直接创建可复用的歌手 Persona。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 本端点无版本维度：不要传 version——传了会被丢弃、也不影响计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id。缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 Persona 名称；缺失直接返回 400。 描述。 风格。 人声片段起点（秒），必须大于等于 0。建议与 vocal_end_s 成对提供。 人声片段终点（秒），必须大于起点且不能超过已知源时长。 完成后读取 result.persona_id。Persona ID 与自定义模型 ID 不同，不能作为 API 的 model 值使用；新流程无需先创建 Vox。 获取结果：本接口为异步任务。提交后拿到 task_id，按 3–5s 间隔轮询 GET /v1/music/tasks/{task_id}，直到 status 为 completed 或 failed（通常 30–120s；生成中 status 可能为 pending 或 processing，progress 为 0–100 的整数且不保证按固定节点变化）。结果里含 persona 信息。失败时 data.error.message 给出原因，且预扣额度自动退回。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

提取 Vox（已弃用）

计费说明：按路径模型名计费（如 suno-generation）；任务成功后按实际上游消耗结算（部分工具类按次），失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

  • 兼容旧流程的人声片段提取接口；新接入请直接创建 Persona。
  • 引用源音轨：task_id + audio_index 指定，无需记录任何额外 id
  • 异步任务：提交返回 task_id，轮询 GET /v1/music/tasks/:task_id 获取结果

引用源音轨：基于已有歌曲的操作无需记任何额外 id，只需传 task_id（产出源音轨那次任务的 task_id）+ audio_index（结果 data.result.music[] 里第几首，1-based，默认 1）。 本端点无版本维度：不要传 version——传了会被丢弃、也不影响计费。

Authorizations

所有接口均需要使用Bearer Token进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

Body

音频模型。当前传 suno（不传默认 suno）。 产出源音轨那次任务的 task_id。缺失或无法解析源时提交期直接返回 400。 引用源任务结果 data.result.music[] 中的第几首（1-based；默认 1；一次生成通常 2 首：索引 1 与 2）。 截取起点（秒）。 截取终点（秒）。 该功能已弃用。新接入请直接使用 Persona 页面创建 Persona；vox_audio_id 不再作为新流程的必填项。 获取结果：本接口为异步任务。提交后拿到 task_id，轮询 GET /v1/music/tasks/{task_id} 直到 status 为 completed 或 failed。新 Persona 流程不依赖该结果。

Response

响应状态码 返回数据数组

任务状态

  • submitted - 已提交 任务唯一标识符（用于轮询 GET /v1/music/tasks/{task_id} 获取结果）

生成音乐

计费说明：按路径 SKU 计费（例如 flowmusic-generation）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

Flow Music 文字生成音乐。支持风格提示词 / 歌词 / BPM / 时长控制，每次请求生成一首音乐

认证

所有接口均需要使用 Bearer Token 进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

请求参数

模型名称，固定传 "flowmusic"（大小写不敏感） 音乐风格或声音描述提示词

示例："upbeat pop music with piano"

sound_prompt 与 lyrics 不可同时为空（至少传一个）。每次请求仅生成一首音乐。 歌词文本，可先用生成歌词接口获得后回填

示例："[Verse 1]\n黑夜再长也会天亮\n..." 生成音乐标题 BPM（每分钟节拍数），必须 ≥ 1

示例："120" 生成时长（秒）

支持范围：1 \~ 240 秒 随机种子，用于复现结果

相同的请求下传相同的 seed 值，会生成类似的结果，但不保证完全一致。 ## 响应

响应状态码，成功时为 200 返回数据数组

任务状态，初始提交时为 submitted 任务唯一标识符，用于查询任务状态和结果

使用场景

场景 1：纯风格提示词生成

{
 "model": "flowmusic",
 "title": "My Song",
 "sound_prompt": "upbeat pop music with piano",
 "bpm": "120",
 "length": 60
}

场景 2：歌词 + 风格成曲

{
 "model": "flowmusic",
 "title": "坚持",
 "lyrics": "[Verse 1]\n黑夜再长也会天亮\n...",
 "sound_prompt": "energetic rock with electric guitar",
 "length": 120
}

查询任务结果

音乐生成为异步任务，提交后会返回 task_id。使用 获取任务状态 接口查询生成进度和结果。

任务完成结果示例

查询返回示例（GET /v1/music/tasks/{task_id}）：

{
 "code": 200,
 "data": {
 "id": "task_01KWXVB61E28THHFBSYXWA4FAJ",
 "status": "completed",
 "progress": 100,
 "created": 1783413184,
 "completed": 1783413236,
 "actual_time": 52,
 "cost": 0.048,
 "credits_cost": 0.48,
 "result": {
 "music": [
 {
 "clip_id": "a41aade4-993e-4d28-b56f-d97e7ef7167c",
 "title": "Regression Song",
 "duration_seconds": "181.70666667",
 "create_time": "2026-07-07T08:33:32.854073Z",
 "lyrics": "[Verse 1]\nWaking up to the morning light,\n...",
 "lyrics_id": "c302d603-81b6-552f-8122-e512928d6aa1",
 "lyrics_timing_markers": [[10, 12], [212, 36]],
 "audio_url": "https://cdn.example.com/audio/flowmusic_a41aade4.m4a",
 "wav_url": "https://cdn.example.com/audio/flowmusic_a41aade4.wav",
 "image_url": "https://cdn.example.com/image/flowmusic_a41aade4_cover.jpg"
 }
 ]
 }
 }
}

Lyria 3.5 生成音乐

计费说明：按路径 SKU 计费（例如 flowmusic-generation）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

使用 Lyria 3.5 进行 Flow Music 文字生成音乐，支持风格提示词、歌词、BPM 和时长控制

认证

所有接口均需要使用 Bearer Token 进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

请求参数

模型名称，固定传 "flowmusic"（大小写不敏感） 模型版本，固定传 "lyria-3.5"

Lyria 3.5 仍使用 flowmusic 作为模型名，不要将 model 改为 lyria-3.5 或 flowmusic-lyria-3.5。 音乐风格或声音描述提示词

示例："upbeat pop music with piano"

sound_prompt 与 lyrics 不可同时为空（至少传一个）。每次请求仅生成一首音乐。 歌词文本，可先用生成歌词接口获得后回填

示例："[Verse 1]\n黑夜再长也会天亮\n..." 生成音乐标题 BPM（每分钟节拍数），必须 ≥ 1

示例："120" 生成时长（秒）

支持范围：1 \~ 240 秒 随机种子，用于复现结果

相同的请求下传相同的 seed 值，会生成类似的结果，但不保证完全一致。 ## 响应

响应状态码，成功时为 200 返回数据数组

任务状态，初始提交时为 submitted 任务唯一标识符，用于查询任务状态和结果

使用场景

场景 1：纯风格提示词生成

{
 "model": "flowmusic",
 "version": "lyria-3.5",
 "title": "My Song",
 "sound_prompt": "upbeat pop music with piano",
 "bpm": "120",
 "length": 60
}

场景 2：歌词 + 风格成曲

{
 "model": "flowmusic",
 "version": "lyria-3.5",
 "title": "坚持",
 "lyrics": "[Verse 1]\n黑夜再长也会天亮\n...",
 "sound_prompt": "energetic rock with electric guitar",
 "length": 120
}

查询任务结果

音乐生成为异步任务，提交后会返回 task_id。使用 获取任务状态 接口查询生成进度和结果。

任务完成结果示例

查询返回示例（GET /v1/music/tasks/{task_id}）：

{
 "code": 200,
 "data": {
 "id": "task_01KWXVB61E28THHFBSYXWA4FAJ",
 "status": "completed",
 "progress": 100,
 "created": 1783413184,
 "completed": 1783413236,
 "actual_time": 52,
 "cost": 0.048,
 "credits_cost": 0.48,
 "result": {
 "music": [
 {
 "clip_id": "a41aade4-993e-4d28-b56f-d97e7ef7167c",
 "title": "Regression Song",
 "duration_seconds": "181.70666667",
 "create_time": "2026-07-07T08:33:32.854073Z",
 "lyrics": "[Verse 1]\nWaking up to the morning light,\n...",
 "lyrics_id": "c302d603-81b6-552f-8122-e512928d6aa1",
 "lyrics_timing_markers": [[10, 12], [212, 36]],
 "audio_url": "https://cdn.example.com/audio/flowmusic_a41aade4.m4a",
 "wav_url": "https://cdn.example.com/audio/flowmusic_a41aade4.wav",
 "image_url": "https://cdn.example.com/image/flowmusic_a41aade4_cover.jpg"
 }
 ]
 }
 }
}

生成歌词

计费说明：按路径 SKU 计费（例如 flowmusic-generation）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

Flow Music 根据提示词生成歌词。结果可回填到生成音乐接口的 lyrics 字段

认证

所有接口均需要使用 Bearer Token 进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

请求参数

模型名称，固定传 "flowmusic"（大小写不敏感） 生成歌词的提示词，≤ 3000 字符

建议描述歌曲主题、风格、情绪等，以获得更贴合的歌词

示例："一首关于坚持的摇滚歌曲"

响应

响应状态码，成功时为 200 返回数据数组

任务状态，初始提交时为 submitted 任务唯一标识符，用于查询任务状态和结果

使用场景

场景 1：按主题生成歌词

{
 "model": "flowmusic",
 "prompt": "一首关于坚持的摇滚歌曲"
}

场景 2：歌词回填成曲

先生成歌词，完成后取 result.lyrics[0] 的 title 和 lyrics，回填到生成音乐接口：

{
 "model": "flowmusic",
 "title": "坚持",
 "lyrics": "[Verse 1]\n黑夜再长也会天亮\n...",
 "sound_prompt": "energetic rock with electric guitar"
}

查询任务结果

歌词生成为异步任务，提交后会返回 task_id。使用 获取任务状态 接口查询生成进度和结果。

任务完成结果示例

查询返回示例（GET /v1/music/tasks/{task_id}）：

{
 "code": 200,
 "data": {
 "id": "task_01KWXVCX91HYHSTHZ0NC1SRFW1",
 "status": "completed",
 "progress": 100,
 "created": 1783413241,
 "completed": 1783413284,
 "actual_time": 43,
 "cost": 0.016,
 "credits_cost": 0.16,
 "result": {
 "lyrics": [
 {
 "title": "Bleached",
 "lyrics": "[Intro]\n(Check)\n(One two)\n\n[Verse 1]\nThe birds are..."
 }
 ]
 }
 }
}

音乐延伸

计费说明：按路径 SKU 计费（例如 flowmusic-generation）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

Flow Music 对已生成的音频续写。从指定时间点开始，按编辑指令延伸音乐

认证

所有接口均需要使用 Bearer Token 进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

请求参数

模型名称，固定传 "flowmusic"（大小写不敏感） 源音乐 clip_id，来自已成功任务的 result.music[].clip_id

源任务必须已成功。外部音频可先通过上传音频导入换取 clip_id。 开始续写的时间点（秒）

不能超过源 clip 时长 续写时长（秒）

最大值：164 秒 续写音乐的编辑指令

示例："延续主歌旋律，加入弦乐" 续写后音乐标题 随机种子，用于复现结果

响应

响应状态码，成功时为 200 返回数据数组

任务状态，初始提交时为 submitted 任务唯一标识符，用于查询任务状态和结果

使用场景

场景 1：从副歌处续写 60 秒

{
 "model": "flowmusic",
 "clip_id": "abc123-def456",
 "extend_from_s": 30,
 "extend_s": 60,
 "instruction": "延续主歌旋律，加入弦乐"
}

查询任务结果

音乐延伸为异步任务，提交后会返回 task_id。使用 获取任务状态 接口查询生成进度和结果。延伸产物是新的 clip_id，后续操作请使用新 clip_id。

任务完成结果示例

查询返回示例（GET /v1/music/tasks/{task_id}）：

{
 "code": 200,
 "data": {
 "id": "task_01KWXVCYB70YJ1WY9X22RVYRNP",
 "status": "completed",
 "progress": 100,
 "created": 1783413242,
 "completed": 1783413292,
 "actual_time": 50,
 "cost": 0.048,
 "credits_cost": 0.48,
 "result": {
 "music": [
 {
 "clip_id": "d2f589ea-5390-4e83-8e2f-4517420408fa",
 "title": "Untitled (Extended)",
 "duration_seconds": "39.95733333",
 "create_time": "2026-07-07T08:34:33.240020Z",
 "lyrics": "waking up to the morning light,\n...",
 "lyrics_id": "0452451b-9e54-5d9f-8437-8bff97c7bbc8",
 "lyrics_timing_markers": [[0, 12], [129, 20]],
 "audio_url": "https://cdn.example.com/audio/flowmusic_d2f589ea.m4a",
 "wav_url": "https://cdn.example.com/audio/flowmusic_d2f589ea.wav",
 "image_url": "https://cdn.example.com/image/flowmusic_d2f589ea_cover.jpg"
 }
 ]
 }
 }
}

Lyria 3.5 音乐延伸

计费说明：按路径 SKU 计费（例如 flowmusic-generation）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

使用 Lyria 3.5 从指定时间点延伸已生成的音乐

认证

所有接口均需要使用 Bearer Token 进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

请求参数

模型名称，固定传 "flowmusic"（大小写不敏感） 模型版本，固定传 "lyria-3.5"

Lyria 3.5 仍使用 flowmusic 作为模型名，不要将 model 改为 lyria-3.5 或 flowmusic-lyria-3.5。 源音乐 clip_id，来自已成功任务的 result.music[].clip_id

源任务必须已成功。外部音频可先通过上传音频导入换取 clip_id。 开始续写的时间点（秒）

不能超过源 clip 时长 续写时长（秒）

最大值：164 秒 续写音乐的编辑指令

示例："延续主歌旋律，加入弦乐" 续写后音乐标题 随机种子，用于复现结果

响应

响应状态码，成功时为 200 返回数据数组

任务状态，初始提交时为 submitted 任务唯一标识符，用于查询任务状态和结果

使用场景

场景 1：从副歌处续写 60 秒

{
 "model": "flowmusic",
 "version": "lyria-3.5",
 "clip_id": "abc123-def456",
 "extend_from_s": 30,
 "extend_s": 60,
 "instruction": "延续主歌旋律，加入弦乐"
}

查询任务结果

音乐延伸为异步任务，提交后会返回 task_id。使用 获取任务状态 接口查询生成进度和结果。延伸产物是新的 clip_id，后续操作请使用新 clip_id。

任务完成结果示例

查询返回示例（GET /v1/music/tasks/{task_id}）：

{
 "code": 200,
 "data": {
 "id": "task_01KWXVCYB70YJ1WY9X22RVYRNP",
 "status": "completed",
 "progress": 100,
 "created": 1783413242,
 "completed": 1783413292,
 "actual_time": 50,
 "cost": 0.048,
 "credits_cost": 0.48,
 "result": {
 "music": [
 {
 "clip_id": "d2f589ea-5390-4e83-8e2f-4517420408fa",
 "title": "Untitled (Extended)",
 "duration_seconds": "39.95733333",
 "create_time": "2026-07-07T08:34:33.240020Z",
 "lyrics": "waking up to the morning light,\n...",
 "lyrics_id": "0452451b-9e54-5d9f-8437-8bff97c7bbc8",
 "lyrics_timing_markers": [[0, 12], [129, 20]],
 "audio_url": "https://cdn.example.com/audio/flowmusic_d2f589ea.m4a",
 "wav_url": "https://cdn.example.com/audio/flowmusic_d2f589ea.wav",
 "image_url": "https://cdn.example.com/image/flowmusic_d2f589ea_cover.jpg"
 }
 ]
 }
 }
}

片段替换

计费说明：按路径 SKU 计费（例如 flowmusic-generation）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

Flow Music 替换已生成音频中的某一段。按编辑指令重新生成 start_s 到 end_s 之间的片段

认证

所有接口均需要使用 Bearer Token 进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

请求参数

模型名称，固定传 "flowmusic"（大小写不敏感） 源音乐 clip_id，来自已成功任务的 result.music[].clip_id 替换开始时间（秒） 替换结束时间（秒）

end_s 必须大于 start_s，且不能超过源 clip 时长。 替换片段的编辑指令

示例："替换为钢琴版本" 替换后音乐标题 随机种子，用于复现或控制生成结果

响应

响应状态码，成功时为 200 返回数据数组

任务状态，初始提交时为 submitted 任务唯一标识符，用于查询任务状态和结果

使用场景

场景 1：把 10-20 秒替换为钢琴版本

{
 "model": "flowmusic",
 "clip_id": "abc123-def456",
 "start_s": 10,
 "end_s": 20,
 "instruction": "替换为钢琴版本"
}

查询任务结果

片段替换为异步任务，提交后会返回 task_id。使用 获取任务状态 接口查询生成进度和结果。替换产物是新的 clip_id（整首歌重新输出，其中指定区间已被替换），后续操作请使用新 clip_id。

任务完成结果示例

查询返回示例（GET /v1/music/tasks/{task_id}）：

{
 "code": 200,
 "data": {
 "id": "task_01KWXVHGTG5JM33S8FG1K90YQ6",
 "status": "completed",
 "progress": 100,
 "created": 1783413392,
 "completed": 1783413454,
 "actual_time": 62,
 "cost": 0.048,
 "credits_cost": 0.48,
 "result": {
 "music": [
 {
 "clip_id": "9508d1fe-633e-464b-8a40-c6368e5464fa",
 "title": "Untitled (Replaced)",
 "duration_seconds": "181.58933333",
 "create_time": "2026-07-07T08:37:13.864452Z",
 "lyrics": "[Verse 1]\nWaking up to the morning light,\n...",
 "lyrics_id": "c302d603-81b6-552f-8122-e512928d6aa1",
 "lyrics_timing_markers": [[10, 12], [71, 15]],
 "audio_url": "https://cdn.example.com/audio/flowmusic_9508d1fe.m4a",
 "wav_url": "https://cdn.example.com/audio/flowmusic_9508d1fe.wav",
 "image_url": "https://cdn.example.com/image/flowmusic_9508d1fe_cover.jpg"
 }
 ]
 }
 }
}

Lyria 3.5 片段替换

计费说明：按路径 SKU 计费（例如 flowmusic-generation）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

使用 Lyria 3.5 替换已生成音频中的指定片段

认证

所有接口均需要使用 Bearer Token 进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

请求参数

模型名称，固定传 "flowmusic"（大小写不敏感） 模型版本，固定传 "lyria-3.5"

Lyria 3.5 仍使用 flowmusic 作为模型名，不要将 model 改为 lyria-3.5 或 flowmusic-lyria-3.5。 源音乐 clip_id，来自已成功任务的 result.music[].clip_id 替换开始时间（秒） 替换结束时间（秒）

end_s 必须大于 start_s，且不能超过源 clip 时长。 替换片段的编辑指令

示例："替换为钢琴版本" 替换后音乐标题 随机种子，用于复现或控制生成结果

响应

响应状态码，成功时为 200 返回数据数组

任务状态，初始提交时为 submitted 任务唯一标识符，用于查询任务状态和结果

使用场景

场景 1：把 10-20 秒替换为钢琴版本

{
 "model": "flowmusic",
 "version": "lyria-3.5",
 "clip_id": "abc123-def456",
 "start_s": 10,
 "end_s": 20,
 "instruction": "替换为钢琴版本"
}

查询任务结果

片段替换为异步任务，提交后会返回 task_id。使用 获取任务状态 接口查询生成进度和结果。替换产物是新的 clip_id（整首歌重新输出，其中指定区间已被替换），后续操作请使用新 clip_id。

任务完成结果示例

查询返回示例（GET /v1/music/tasks/{task_id}）：

{
 "code": 200,
 "data": {
 "id": "task_01KWXVHGTG5JM33S8FG1K90YQ6",
 "status": "completed",
 "progress": 100,
 "created": 1783413392,
 "completed": 1783413454,
 "actual_time": 62,
 "cost": 0.048,
 "credits_cost": 0.48,
 "result": {
 "music": [
 {
 "clip_id": "9508d1fe-633e-464b-8a40-c6368e5464fa",
 "title": "Untitled (Replaced)",
 "duration_seconds": "181.58933333",
 "create_time": "2026-07-07T08:37:13.864452Z",
 "lyrics": "[Verse 1]\nWaking up to the morning light,\n...",
 "lyrics_id": "c302d603-81b6-552f-8122-e512928d6aa1",
 "lyrics_timing_markers": [[10, 12], [71, 15]],
 "audio_url": "https://cdn.example.com/audio/flowmusic_9508d1fe.m4a",
 "wav_url": "https://cdn.example.com/audio/flowmusic_9508d1fe.wav",
 "image_url": "https://cdn.example.com/image/flowmusic_9508d1fe_cover.jpg"
 }
 ]
 }
 }
}

Cover 改编

计费说明：按路径 SKU 计费（例如 flowmusic-generation）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

Flow Music 对整首歌做风格改编（翻唱 / 改风格），strength 控制编辑强度

认证

所有接口均需要使用 Bearer Token 进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

请求参数

模型名称，固定传 "flowmusic"（大小写不敏感） 源音乐的唯一标识符，来自已成功任务的 result.music[].clip_id Cover 编辑指令

示例："将这首歌曲改为爵士风格" 编辑强度

取值范围：0 \~ 1，越大改动越大 Cover 后的音乐标题 随机种子，用于结果复现

响应

响应状态码，成功时为 200 返回数据数组

任务状态，初始提交时为 submitted 任务唯一标识符，用于查询任务状态和结果

使用场景

场景 1：整曲改为爵士风格

{
 "model": "flowmusic",
 "clip_id": "abc123-def456",
 "instruction": "将这首歌曲改为爵士风格",
 "strength": 0.5
}

场景 2：外部音频导入后改编

先通过上传音频把外部音频导入换取 clip_id，再做 Cover：

{
 "model": "flowmusic",
 "clip_id": "1db3a20f-4ddc-44e8-8c9c-6c9093c16ffe",
 "instruction": "改成爵士风格",
 "strength": 0.6
}

查询任务结果

Cover 改编为异步任务，提交后会返回 task_id。使用 获取任务状态 接口查询生成进度和结果。Cover 产物是新的 clip_id，后续操作请使用新 clip_id。

任务完成结果示例

查询返回示例（GET /v1/music/tasks/{task_id}）：

{
 "code": 200,
 "data": {
 "id": "task_01KWXVD0E653EZ9FWD2SD9NNB6",
 "status": "completed",
 "progress": 100,
 "created": 1783413244,
 "completed": 1783413315,
 "actual_time": 71,
 "cost": 0.048,
 "credits_cost": 0.48,
 "result": {
 "music": [
 {
 "clip_id": "ef3d804e-fa97-402f-ba17-4ff08270159b",
 "title": "Untitled (Cover)",
 "duration_seconds": "178.03733333",
 "create_time": "2026-07-07T08:34:58.112190Z",
 "lyrics": "[Verse 1]\nWaking up to the morning light,\n...",
 "lyrics_id": "c302d603-81b6-552f-8122-e512928d6aa1",
 "lyrics_timing_markers": [[10, 12], [212, 36]],
 "audio_url": "https://cdn.example.com/audio/flowmusic_ef3d804e.m4a",
 "wav_url": "https://cdn.example.com/audio/flowmusic_ef3d804e.wav",
 "image_url": "https://cdn.example.com/image/flowmusic_ef3d804e_cover.jpg"
 }
 ]
 }
 }
}

Lyria 3.5 Cover 改编

计费说明：按路径 SKU 计费（例如 flowmusic-generation）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

使用 Lyria 3.5 对整首音乐进行风格改编

认证

所有接口均需要使用 Bearer Token 进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

请求参数

模型名称，固定传 "flowmusic"（大小写不敏感） 模型版本，固定传 "lyria-3.5"

Lyria 3.5 仍使用 flowmusic 作为模型名，不要将 model 改为 lyria-3.5 或 flowmusic-lyria-3.5。 源音乐的唯一标识符，来自已成功任务的 result.music[].clip_id Cover 编辑指令

示例："将这首歌曲改为爵士风格" 编辑强度

取值范围：0 \~ 1，越大改动越大 Cover 后的音乐标题 随机种子，用于结果复现

响应

响应状态码，成功时为 200 返回数据数组

任务状态，初始提交时为 submitted 任务唯一标识符，用于查询任务状态和结果

使用场景

场景 1：整曲改为爵士风格

{
 "model": "flowmusic",
 "version": "lyria-3.5",
 "clip_id": "abc123-def456",
 "instruction": "将这首歌曲改为爵士风格",
 "strength": 0.5
}

场景 2：外部音频导入后改编

先通过上传音频把外部音频导入换取 clip_id，再做 Cover：

{
 "model": "flowmusic",
 "version": "lyria-3.5",
 "clip_id": "1db3a20f-4ddc-44e8-8c9c-6c9093c16ffe",
 "instruction": "改成爵士风格",
 "strength": 0.6
}

查询任务结果

Cover 改编为异步任务，提交后会返回 task_id。使用 获取任务状态 接口查询生成进度和结果。Cover 产物是新的 clip_id，后续操作请使用新 clip_id。

任务完成结果示例

查询返回示例（GET /v1/music/tasks/{task_id}）：

{
 "code": 200,
 "data": {
 "id": "task_01KWXVD0E653EZ9FWD2SD9NNB6",
 "status": "completed",
 "progress": 100,
 "created": 1783413244,
 "completed": 1783413315,
 "actual_time": 71,
 "cost": 0.048,
 "credits_cost": 0.48,
 "result": {
 "music": [
 {
 "clip_id": "ef3d804e-fa97-402f-ba17-4ff08270159b",
 "title": "Untitled (Cover)",
 "duration_seconds": "178.03733333",
 "create_time": "2026-07-07T08:34:58.112190Z",
 "lyrics": "[Verse 1]\nWaking up to the morning light,\n...",
 "lyrics_id": "c302d603-81b6-552f-8122-e512928d6aa1",
 "lyrics_timing_markers": [[10, 12], [212, 36]],
 "audio_url": "https://cdn.example.com/audio/flowmusic_ef3d804e.m4a",
 "wav_url": "https://cdn.example.com/audio/flowmusic_ef3d804e.wav",
 "image_url": "https://cdn.example.com/image/flowmusic_ef3d804e_cover.jpg"
 }
 ]
 }
 }
}

词曲分离

计费说明：按路径 SKU 计费（例如 flowmusic-generation）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

Flow Music 分离人声 / 伴奏音轨，结果为 zip 分轨包

认证

所有接口均需要使用 Bearer Token 进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

请求参数

模型名称，固定传 "flowmusic"（大小写不敏感） 需要分离音轨的音乐 clip_id，来自已成功任务的 result.music[].clip_id

响应

响应状态码，成功时为 200 返回数据数组

任务状态，初始提交时为 submitted 任务唯一标识符，用于查询任务状态和结果

使用场景

场景 1：分离人声与伴奏

{
 "model": "flowmusic",
 "clip_id": "abc123-def456"
}

查询任务结果

词曲分离为异步任务，提交后会返回 task_id。使用 获取任务状态 接口查询生成进度和结果。分离结果是一个 zip 打包文件（result.music[0].file_url，约 20MB），内含人声 / 伴奏等分轨音频，提供下载即可。

任务完成结果示例

查询返回示例（GET /v1/music/tasks/{task_id}）：

{
 "code": 200,
 "data": {
 "id": "task_01KWXVD1EFXYEHDJ8M0XNJ65AR",
 "status": "completed",
 "progress": 100,
 "created": 1783413245,
 "completed": 1783413331,
 "actual_time": 86,
 "cost": 0.048,
 "credits_cost": 0.48,
 "result": {
 "music": [
 {
 "clip_id": "a41aade4-993e-4d28-b56f-d97e7ef7167c",
 "file_url": "https://cdn.example.com/audio/flowmusic_a41aade4_stems.zip",
 "url": "https://cdn.example.com/audio/flowmusic_a41aade4_stems.zip",
 "mime_type": "application/zip",
 "size_bytes": 20323367
 }
 ]
 }
 }
}

上传音频

计费说明：按路径 SKU 计费（例如 flowmusic-generation）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

把外部音频导入 Flow Music，换取 clip_id 供后续延伸 / 替换 / Cover / 分离使用

认证

所有接口均需要使用 Bearer Token 进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

请求参数

模型名称，固定传 "flowmusic"（大小写不敏感） 待上传音频文件地址，需公网可访问

仅支持常见音频文件后缀（如 .mp3 / .wav）。 ## 响应

响应状态码，成功时为 200 返回数据数组

任务状态，初始提交时为 submitted 任务唯一标识符，用于查询任务状态和结果

使用场景

场景 1：导入外部音频换取 clip_id

{
 "model": "flowmusic",
 "audio_url": "https://example.com/audio.mp3"
}

完成后从 result.music[0].clip_id 取导入产物的 clip_id，即可用于延伸 / 替换 / Cover / 分离。

查询任务结果

上传音频为异步任务，提交后会返回 task_id。使用 获取任务状态 接口查询生成进度和结果。

任务完成结果示例

查询返回示例（GET /v1/music/tasks/{task_id}）：

{
 "code": 200,
 "data": {
 "id": "task_01KWXVD2FC61SYZ5103Z4XCCS5",
 "status": "completed",
 "progress": 100,
 "created": 1783413246,
 "completed": 1783413282,
 "actual_time": 36,
 "cost": 0.008,
 "credits_cost": 0.08,
 "result": {
 "music": [
 {
 "clip_id": "1db3a20f-4ddc-44e8-8c9c-6c9093c16ffe",
 "audio_url": "https://cdn.example.com/audio/flowmusic_1db3a20f_upload_audio.wav",
 "url": "https://cdn.example.com/audio/flowmusic_1db3a20f_upload_audio.wav"
 }
 ]
 }
 }
}

下载音频

计费说明：按路径 SKU 计费（例如 flowmusic-generation）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

Flow Music 将 clip 转出为指定格式（wav / mp3）的音频文件

认证

所有接口均需要使用 Bearer Token 进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

请求参数

模型名称，固定传 "flowmusic"（大小写不敏感） 需要下载的音乐 clip_id，来自已成功任务的 result.music[].clip_id 下载格式

可选值：

  • mp3 - 有损压缩，体积小
  • wav - 无损，适合后期制作

响应

响应状态码，成功时为 200 返回数据数组

任务状态，初始提交时为 submitted 任务唯一标识符，用于查询任务状态和结果

使用场景

场景 1：转出无损 wav

{
 "model": "flowmusic",
 "clip_id": "abc123-def456",
 "format": "wav"
}

查询任务结果

下载音频为异步任务，提交后会返回 task_id。使用 获取任务状态 接口查询生成进度和结果。结果统一在 result.music[0].audio_url（url 同值），format / mime_type 字段标识实际格式。

任务完成结果示例

查询返回示例（GET /v1/music/tasks/{task_id}）：

{
 "code": 200,
 "data": {
 "id": "task_01KWXVD3FPYYQPJ2N87XXE5NQG",
 "status": "completed",
 "progress": 100,
 "created": 1783413247,
 "completed": 1783413296,
 "actual_time": 49,
 "cost": 0.016,
 "credits_cost": 0.16,
 "result": {
 "music": [
 {
 "clip_id": "a41aade4-993e-4d28-b56f-d97e7ef7167c",
 "format": "wav",
 "mime_type": "audio/wav",
 "size_bytes": 34900726,
 "audio_url": "https://cdn.example.com/audio/flowmusic_a41aade4_download_audio.wav",
 "url": "https://cdn.example.com/audio/flowmusic_a41aade4_download_audio.wav"
 }
 ]
 }
 }
}

音乐视频渲染

计费说明：按路径 SKU 计费（例如 flowmusic-generation）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

Flow Music 按模板把音乐渲染成 mp4 视频，支持 simple / modern / player 三种预设

认证

所有接口均需要使用 Bearer Token 进行认证

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

请求参数

模型名称，固定传 "flowmusic"（大小写不敏感） 需要生成视频的音乐 clip_id，来自已成功任务的 result.music[].clip_id 视频模板预设

可选值：

  • simple - 简洁模板
  • modern - 现代风格模板
  • player - 播放器风格模板

响应

响应状态码，成功时为 200 返回数据数组

任务状态，初始提交时为 submitted 任务唯一标识符，用于查询任务状态和结果

使用场景

场景 1：用 modern 模板渲染音乐视频

{
 "model": "flowmusic",
 "clip_id": "abc123-def456",
 "preset": "modern"
}

查询任务结果

音乐视频渲染为异步任务，提交后会返回 task_id。使用 获取任务状态 接口查询生成进度和结果。结果在 result.music[0].video_url。

任务完成结果示例

查询返回示例（GET /v1/music/tasks/{task_id}）：

{
 "code": 200,
 "data": {
 "id": "task_01KWXVD4HQEEY7B5NJ31177Q1H",
 "status": "completed",
 "progress": 100,
 "created": 1783413248,
 "completed": 1783413327,
 "actual_time": 79,
 "cost": 0.016,
 "credits_cost": 0.16,
 "result": {
 "music": [
 {
 "clip_id": "a41aade4-993e-4d28-b56f-d97e7ef7167c",
 "video_url": "https://cdn.example.com/video/flowmusic_a41aade4_video_clip.mp4",
 "url": "https://cdn.example.com/video/flowmusic_a41aade4_video_clip.mp4"
 }
 ]
 }
 }
}

查询任务

计费说明：按路径 SKU 计费（例如 flowmusic-generation）；任务成功后按实际上游消耗结算，失败全额退款；金额以控制台预估 / 实扣为准。轮询 GET /v1/music/tasks/{task_id}。

查询 Flow Music 异步任务的执行状态、进度和生成结果

鉴权

所有 Flow Music 接口都需要 Bearer Token 鉴权

获取 API Key：

登录 控制台 →「API 令牌」获取 API Key。

添加到请求头：

Authorization: Bearer YOUR_API_KEY

路径参数

提交 Flow Music 任务后返回的任务 ID

任务 ID 来自提交接口响应中的 data[0].task_id。 ## 查询参数

错误信息和部分提示文案的语言

可选值：zh、en、ja、ko

响应字段

响应状态码，成功时为 200 任务详情

任务 ID 任务状态：pending、processing、completed、failed 任务进度，范围 0-100 实际扣费金额；任务失败时通常为 0 实际消耗的 credits 任务完成后的生成结果；不同 Flow Music 能力返回的字段不同

结果结构

音乐类任务

生成音乐、音乐延伸、片段替换、Cover 改编、词曲分离、上传音频、下载音频和视频渲染通常返回 result.music 数组。

{
 "result": {
 "music": [
 {
 "clip_id": "a41aade4-993e-4d28-b56f-d97e7ef7167c",
 "audio_url": "https://cdn.example.com/audio/flowmusic_a41aade4.m4a",
 "wav_url": "https://cdn.example.com/audio/flowmusic_a41aade4.wav",
 "video_url": "https://cdn.example.com/video/flowmusic_a41aade4.mp4",
 "file_url": "https://cdn.example.com/audio/flowmusic_a41aade4_stems.zip"
 }
 ]
 }
}

歌词任务

生成歌词返回 result.lyrics 数组。

{
 "result": {
 "lyrics": [
 {
 "title": "Bleached",
 "lyrics": "[Intro]\n(Check)\n(One two)\n..."
 }
 ]
 }
}

使用说明

Flow Music 提交接口都是异步任务。提交成功后先获取 task_id，再调用本接口轮询任务状态；当 status 为 completed 时，从 result 中读取生成结果。

常见问题

zhenzhen-image-g-v2-* 和 zhenzhen-image-g2-* 有什么区别？

是两套不同模型：参数、分辨率与计费均不同。扩展模型见 Zhenzhen 扩展；G-2 见模型列表中的 Zhenzhen Image G-2。

Midjourney 新接口和旧版 /mj/* 有什么区别？

新版走 /v1/midjourney/*（），计费 SKU 为 midjourney-*；旧版 /mj/* 是另一套 Discord 代理协议，请勿混用。

Suno 和 Seed Audio / Whisper 有什么区别？

完全不同路径：Suno 用 /v1/music/*；Seed Audio 用 /v1/audio/generations；Whisper 用 /v1/audio/transcriptions。计费 SKU 看路径（suno-*），不是 body.model。详见 Suno。

能直接用 OpenAI 官方 SDK 调用吗？

/v1/videos 接口对齐了 OpenAI Video API 的字段风格（prompt / status / metadata 等），但目前主流 OpenAI 官方 SDK 尚未开放 Video 相关方法，建议直接用 HTTP 客户端按本文档调用（见快速开始的三语言示例）。

图生视频最多传几张图？

顶层 images 最多 2 张：第 1 张为首帧（必填），第 2 张为尾帧（可选）。JPG / JPEG / PNG / WEBP，单张 ≤ 30MB。

多模态模型（-multi）能同时传图片 + 视频 + 音频吗？

可以，把它们都放进 metadata.content 数组即可：图片最多 9 张、视频最多 3 个（MP4）、音频最多 3 个（MP3 / WAV），至少提供一种参考素材。注意此时不要再单独传顶层 images，它会被 content 整体覆盖。

参考素材怎么「上传」？

用 POST /v1/files/upload 上传文件，拿到 24 小时有效的直链 URL 后填入请求；也可以直接使用自己对象存储（COS / OSS / S3）的公网直链，详见参考素材指南。

seconds 可以传任意秒数吗？

支持 "4" ~ "15" 的整数或 "-1"（自动时长），超出范围以上游返回的错误为准。

生成一个视频大概要多久？

通常在提交后 10~30 分钟内出结果，与档位、分辨率、时长和排队情况有关。请按 3~5 秒间隔轮询查询接口，不要依赖固定等待时间。

视频链接会过期吗？

会。metadata.url（视频）与 result_url（图片 / 音频）都是带签名有效期的临时地址，请在任务完成后及时下载并转存到自己的存储。

如何调用视频超分？

模型用 zhenzhen-upscaler，走 POST /v1/videos；在 metadata.content 里传一条输入视频的 video_url，用 metadata.resolution 指定目标分辨率（720p / 1080p / 2k / 4k）。完整说明见 视频超分。

如何调用 Seedream 图片生成？

使用 POST /v1/image/generations。V5 Pro 与 V5 Flash 均有文生图 -t2i、图生图 -i2i 和图层拆分 -layer-decomposition；海外 Flash 使用 dola-seedream-5.0-flash-*。查询用 GET /v1/image/generations/{task_id}，主图读 data.result_url，图层完整 URL 列表读 data.data.content.image_urls。

如何调用 Seed Audio 音频生成？

使用 POST /v1/audio/generations（不是同步 TTS /v1/audio/speech），模型 doubao-seed-audio-1.0。查询用 GET /v1/audio/generations/{task_id}，成功后读 data.result_url。

如何调用 Whisper 语音转写？

使用 POST /v1/audio/transcriptions，模型 whisper-1，multipart 上传音频后同步返回文本。按时长计费（1 分钟 = 1000 tokens）。勿与异步 Seed Audio /v1/audio/generations 混淆。

图片的 resolution 和 width/height 怎么选？

传了 metadata.resolution（1k / 2k）时优先用它，忽略宽高；不传 resolution 时可自定义 width / height（240~8192）。