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

Imagine（文生图）

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

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

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

请求参数

结构化参数（可选）

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

参数

请求示例

三档比例（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 同步返回，但仍走平台标准异步流——提交后照常轮询查询。

参数

请求示例

{
 "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 改写整张图。适合背景替换、风格迁移、内容修改。

参数

结构化参数（可选）

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

请求示例

{
 "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 张图里截取实现，本地合成、通常瞬时返回。

参数

请求示例

按 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 版本对应不同命令：

HD upscale 示例

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

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

与普通 upscale 对比

⚠️ 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。

参数

请求示例

{
 "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。

参数

自动匹配

优先匹配 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。

参数

自动匹配

优先匹配 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。

参数

自动匹配

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

请求示例

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

错误响应

返回

提交成功返回新的本地 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×），两者均直接出图。

参数

自动匹配

请求示例

{
 "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（向右后继续向右），适合拼全景图。

参数

自动匹配按 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 才能完成。

参数

自动匹配

服务端从原任务 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 → 局部重绘；无 → 外扩。

参数

mask 要求

请求示例

{
 "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 秒。

参数

video_type 合法值

不接受带 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。

参数

力度对比

请求示例

强烈重塑：

{
 "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。

状态字段总览

查询说明

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

高级：使用 custom_id 直接操作

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

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

创建自定义模型

计费说明：按路径模型名计费（如 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 生成选项

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

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

文本与权重限制

操作接口的新请求使用 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 为原因，自动退回预扣额度。