Midjourney 图片模型(Beta),默认 V8.2。提示词和参数照 midjourney.com 的写法;一次出一组 4 张 PNG 原图,按次计费,接着放大、变体、Remix、扩图、平移也是同一个接口。
在 Playground 试用 →快速开始
和其他图片接口一样是异步任务:提交得到任务 id,轮询拿结果。下面三步是文生图、查结果、放大第 2 张。
第 1 步:提交文生图(参数写在提示词末尾)
curl https://kovapi.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2", "speed": "fast"}'返回(HTTP 202)
{
"id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
"object": "image.generation.job",
"status": "queued",
"created": 1795248736,
"model": "midjourney"
}第 2 步 · 每 2–3 秒查询一次,直到 status 变成 succeeded 或 failed
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \ -H "Authorization: Bearer YOUR_API_KEY"
data 是 4 张 PNG 原图(按 1–4 的顺序),actions 是这单接下来能做的动作。
{
"id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
"object": "image.generation.job",
"status": "succeeded",
"created": 1795248736,
"model": "midjourney",
"data": [
{"url": "https://img.kovapi.com/i/5b2c0e8a1f3d4c6b9a7e2d1c0b3a4f5e.png"},
{"url": "https://img.kovapi.com/i/0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f.png"},
{"url": "https://img.kovapi.com/i/7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d.png"},
{"url": "https://img.kovapi.com/i/3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b.png"}
],
"usage": {"images": 4, "model": "midjourney", "speed": "fast", "action": "imagine"},
"actions": ["upscale", "vary", "remix", "reroll", "zoom", "pan"]
}第 3 步:接着加工——放大第 2 张(同一个接口,传 task_id、action、index)
curl https://kovapi.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "midjourney", "task_id": "img_7f3c9a1e2b4d6f8a0c1e3b5d", "action": "upscale", "index": 2, "mode": "subtle"}'完整示例(Python:提交 → 等待 → 保存到本地)
import time
import requests
BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
def run(body):
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json=body).json()
if "error" in job:
raise SystemExit(job["error"]["message"])
while job["status"] not in ("succeeded", "failed"):
time.sleep(5)
job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()
if job["status"] == "failed":
raise SystemExit(job["error"]["message"])
return job
# 文生图,再把第 2 张放大
grid = run({"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2"})
print([d["url"] for d in grid["data"]], grid["actions"])
big = run({"model": "midjourney", "task_id": grid["id"], "action": "upscale", "index": 2})
with open("midjourney-2.png", "wb") as f:
f.write(requests.get(big["data"][0]["url"]).content)认证
Authorization: Bearer YOUR_API_KEY Content-Type: application/json
在控制台创建 API Key 后即可调用。
参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型 ID,此处为 midjourney。 |
| prompt | string | 否 | 提示词,Midjourney 参数照官方写法写在末尾(--ar、--v、--niji、--s、--c、--w、--seed、--no、--sref、--oref、--cref、--iw、--raw、--tile、--hd、--draft)。文生图、remix、edit 必填;最多 6000 字符。不支持 --repeat 和 {a, b}。 |
| speed | string | 否 | relax(默认,$0.045)、fast($0.055)或 turbo($0.10)。也可以在提示词里写 --relax / --fast / --turbo,这个字段优先。 |
| images | array | 否 | 垫图(image prompt),最多 5 张,图片链接、data: URI 或 base64;放在提示词前面一起交给 Midjourney,可配合 --iw。action 为 blend 时放 2–5 张要融合的图。 |
| size | string | 否 | 比例(如 3:2)或像素尺寸,提示词里没写 --ar 时换成 --ar;写了 --ar 以提示词为准。edit 两样都没写时按原图比例。 |
| task_id | string | 否 | 要接着加工的任务 id(img_ 开头,已完成、7 天内)。 |
| action | string | 否 | upscale(放大 2 倍,mode subtle / creative)、vary(变体,strength strong / subtle)、remix(换提示词重塑)、reroll(重跑)、zoom(向外扩,zoom 1–2)、pan(平移,direction)、inpaint(局部重绘,mask);不带 task_id 的 blend(融合 2–5 张图)、edit(一张图 + 修改说明)。 |
| index | integer | 否 | 处理第几张(1–4);放大后的单图可以不写。 |
| n | integer | 否 | 只能是 1:一次就是一组 4 张,按一次计费。 |
| callback_url | string | 否 | 任务结束时把结果推送到这个地址,见下文的 Webhook。 |
加工动作(task_id + action)
对一单已完成的任务(7 天内)接着做,和官方 App 的按钮一一对应;结果仍是一单新任务,按所选速度计费。
| action | 要带的字段 | 作用 |
|---|---|---|
| upscale | index, mode | 放大 2 倍:mode subtle(默认,细节不变)或 creative(会补细节);交付 1 张。 |
| vary | index, strength | 以第 index 张为基础出 4 张变体:strength strong(默认)或 subtle。 |
| remix | index, prompt, strength | 保留构图,按新的 prompt 重塑,出 4 张。 |
| reroll | — | 用原提示词整组重跑,出 4 张。 |
| zoom | index, zoom | 向外扩展画面:zoom 1–2(默认 2),出 4 张。 |
| pan | index, direction | 朝 left / right / up / down 延展,出 4 张。 |
| inpaint | index, mask, prompt | 只重画 mask 里白色(或透明)的区域;mask 和原图同比例,会自动缩放到原图尺寸。只有任务结果的 actions 里有 inpaint 时才能用。 |
| blend | images(2–5 张) | 不带 task_id:把 2–5 张图融合成一组 4 张;比例写在 prompt(如 --ar 3:2)。 |
| edit | image, prompt | 不带 task_id:上传一张图,用一句话说明怎么改(V8.2 / 8.1),出 4 张;默认保持原图比例,想换比例在 prompt 里写 --ar 或传 size。 |
价格
按次计费,一次是一组 4 张(放大是 1 张),加工动作按所选速度同价。--hd(V8 系列)按 2 倍,V7 的 --draft 按半价(向下取整到积分),对 HD 图做变体或重跑也按 2 倍。提交时预扣,失败全额退回。
| 速度 | 积分 / 张 | 美元 / 张 |
|---|---|---|
| 慢速 relax(默认) | 9 | $0.045 |
| 快速 fast | 11 | $0.055 |
| 极速 turbo | 20 | $0.10 |
尺寸、版本与限制
- 交付 Midjourney 生成的 PNG 原图(带 Midjourney 自己写入的内容元数据),不裁切、不缩放。尺寸跟比例走:1:1 为 1024×1024、3:2 为 1344×896、16:9 为 1456×816;--hd 和放大是 2 倍。
- 版本:不写为 V8.2,可写 --v 8.1 / 8 / 7 / 6.1 / 6 或 --niji 7 / 6。--hd 只用于 V8 系列,--draft 只用于 V7 和 V8 系列(V8 草图按标准价,可能一次给 24 张)。
- 不支持 --repeat / --r 和 {a, b} 这种一次变多个任务的写法;n 只能是 1。
- 垫图最多 5 张,放在提示词前面交给 Midjourney,可用 --iw 调权重;风格参考用 --sref <图片链接>,V7 的万物参考用 --oref <图片链接>。
- 结果和上传的图片保留 7 天;7 天后的任务不能再加工。
- Describe(图生文)和 Midjourney 视频暂未开放。
任务状态与返回字段
GET /v1/images/jobs/{id} 返回的状态如下,每个字段的说明见 异步任务。建议每 2–3 秒查一次,或者用 Webhook。
| 状态 | 含义 |
|---|---|
| queued | 排队中。返回里带 queue_position(前面还有几个任务)和 eta_seconds(预计等待秒数)。 |
| processing | 生成中。 |
| succeeded | 已完成。结果在 data[0].url,计费明细在 usage。 |
| failed | 失败。原因在 error,预扣的积分已全额退回。 |
同一个账号最多 50 个任务同时生成,更多的任务按提交顺序排队;排队超过 15 分钟还没开始的任务会自动失败并全额退款。任务记录保留 3 天,图片链接保留 7 天。
出图时间
实测(11-21):慢速和快速出 4 张约 1.5–2 分钟,极速约 1.5 分钟;放大约 2 分钟,扩图、平移约 1.3 分钟;带垫图或 Blend 约 4 分钟。高峰时可能更久。
错误与退款
提交时出错会直接返回 HTTP 4xx / 5xx,不建任务、不扣费;提交成功后的失败写在查询结果里,预扣的积分全额退回。全部错误码见 错误码。
提交时返回的错误
| HTTP | code | 原因 | 怎么办 |
|---|---|---|---|
| 400 | invalid_request | 参考图读不到(链接打不开、不是图片、超过 16MB 等,message 写明是第几张、什么原因),/v1/images/edits 没带参考图,或请求体不是 JSON 对象、n 不是整数。 | 按 message 修改后重新提交。 |
| 400 | unsupported_action | 参考图读不到(链接打不开、不是图片、超过 16MB 等,message 写明是第几张、什么原因),/v1/images/edits 没带参考图,或请求体不是 JSON 对象、n 不是整数。 | 按 message 修改后重新提交。 |
| 404 | task_not_found | 参考图读不到(链接打不开、不是图片、超过 16MB 等,message 写明是第几张、什么原因),/v1/images/edits 没带参考图,或请求体不是 JSON 对象、n 不是整数。 | 按 message 修改后重新提交。 |
| 401 | invalid_api_key | Key 不存在、已删除或已停用,或者账号已停用。 | 到控制台「API Keys」页面检查这把 Key。 |
| 402 | insufficient_quota | 余额不够预扣这一单。网关先按这一单可能的最高费用预扣,同时发很多请求时也可能出现。 | 如果是并发突发,稍等几秒重试;否则充值。 |
| 429 | rate_limit_exceeded | 超过了这把 Key 设置的每分钟请求数(按最近 60 秒计)。不带 Retry-After。 | 等几秒再试,或在控制台调高这把 Key 的上限。 |
| 503 | service_unavailable | 我们这边临时出错,例如保存参考素材失败;/v1/responses 暂时无法处理时也返回 503,并带 Retry-After。 | 稍后重试。 |
任务失败(status 为 failed)
| code | 什么时候出现 | 怎么办 |
|---|---|---|
| moderation_blocked | 图片:模型方的安全审核拒绝了提示词或参考图(也可能是 content_policy_violation)。 | 改写提示词或更换参考图;原样重交通常还会被拒。 |
| upstream_error | 其他失败:自动重试后仍然失败、排队 15 分钟还没开始、上游拒绝但没有说明原因等,message 写明具体情况。 | 通常重新提交就能成功。 |
用 Webhook 代替轮询
提交时加上 callback_url,任务一结束(成功或失败),网关就把和查询接口完全一样的结果推送到这个地址,带签名,失败会自动重试。也可以在控制台「设置 → Webhook」里配一个账户级地址。 Webhook 文档 →
curl https://kovapi.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2", "callback_url": "https://your-domain.com/webhook"}'