KovAPIKovAPI
POST https://kovapi.com/v1/images/generations

Midjourney 图片模型(Beta),默认 V8.2。提示词和参数照 midjourney.com 的写法;一次出一组 4 张 PNG 原图,按次计费,接着放大、变体、Remix、扩图、平移也是同一个接口。

在 Playground 试用 →

快速开始

和其他图片接口一样是异步任务:提交得到任务 id,轮询拿结果。下面三步是文生图、查结果、放大第 2 张。

第 1 步:提交文生图(参数写在提示词末尾)

curl
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)

JSON
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1795248736,
  "model": "midjourney"
}

第 2 步 · 每 2–3 秒查询一次,直到 status 变成 succeeded 或 failed

curl
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"

data 是 4 张 PNG 原图(按 1–4 的顺序),actions 是这单接下来能做的动作。

JSON
{
  "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
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:提交 → 等待 → 保存到本地)

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)

认证

Header
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

在控制台创建 API Key 后即可调用。

参数

参数类型必填说明
modelstring是模型 ID,此处为 midjourney。
promptstring否提示词,Midjourney 参数照官方写法写在末尾(--ar、--v、--niji、--s、--c、--w、--seed、--no、--sref、--oref、--cref、--iw、--raw、--tile、--hd、--draft)。文生图、remix、edit 必填;最多 6000 字符。不支持 --repeat 和 {a, b}。
speedstring否relax(默认,$0.045)、fast($0.055)或 turbo($0.10)。也可以在提示词里写 --relax / --fast / --turbo,这个字段优先。
imagesarray否垫图(image prompt),最多 5 张,图片链接、data: URI 或 base64;放在提示词前面一起交给 Midjourney,可配合 --iw。action 为 blend 时放 2–5 张要融合的图。
sizestring否比例(如 3:2)或像素尺寸,提示词里没写 --ar 时换成 --ar;写了 --ar 以提示词为准。edit 两样都没写时按原图比例。
task_idstring否要接着加工的任务 id(img_ 开头,已完成、7 天内)。
actionstring否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(一张图 + 修改说明)。
indexinteger否处理第几张(1–4);放大后的单图可以不写。
ninteger否只能是 1:一次就是一组 4 张,按一次计费。
callback_urlstring否任务结束时把结果推送到这个地址,见下文的 Webhook。

加工动作(task_id + action)

对一单已完成的任务(7 天内)接着做,和官方 App 的按钮一一对应;结果仍是一单新任务,按所选速度计费。

action要带的字段作用
upscaleindex, mode放大 2 倍:mode subtle(默认,细节不变)或 creative(会补细节);交付 1 张。
varyindex, strength以第 index 张为基础出 4 张变体:strength strong(默认)或 subtle。
remixindex, prompt, strength保留构图,按新的 prompt 重塑,出 4 张。
reroll—用原提示词整组重跑,出 4 张。
zoomindex, zoom向外扩展画面:zoom 1–2(默认 2),出 4 张。
panindex, direction朝 left / right / up / down 延展,出 4 张。
inpaintindex, mask, prompt只重画 mask 里白色(或透明)的区域;mask 和原图同比例,会自动缩放到原图尺寸。只有任务结果的 actions 里有 inpaint 时才能用。
blendimages(2–5 张)不带 task_id:把 2–5 张图融合成一组 4 张;比例写在 prompt(如 --ar 3:2)。
editimage, prompt不带 task_id:上传一张图,用一句话说明怎么改(V8.2 / 8.1),出 4 张;默认保持原图比例,想换比例在 prompt 里写 --ar 或传 size。

价格

按次计费,一次是一组 4 张(放大是 1 张),加工动作按所选速度同价。--hd(V8 系列)按 2 倍,V7 的 --draft 按半价(向下取整到积分),对 HD 图做变体或重跑也按 2 倍。提交时预扣,失败全额退回。

速度积分 / 张美元 / 张
慢速 relax(默认)9$0.045
快速 fast11$0.055
极速 turbo20$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,不建任务、不扣费;提交成功后的失败写在查询结果里,预扣的积分全额退回。全部错误码见 错误码。

提交时返回的错误

HTTPcode原因怎么办
400invalid_request参考图读不到(链接打不开、不是图片、超过 16MB 等,message 写明是第几张、什么原因),/v1/images/edits 没带参考图,或请求体不是 JSON 对象、n 不是整数。按 message 修改后重新提交。
400unsupported_action参考图读不到(链接打不开、不是图片、超过 16MB 等,message 写明是第几张、什么原因),/v1/images/edits 没带参考图,或请求体不是 JSON 对象、n 不是整数。按 message 修改后重新提交。
404task_not_found参考图读不到(链接打不开、不是图片、超过 16MB 等,message 写明是第几张、什么原因),/v1/images/edits 没带参考图,或请求体不是 JSON 对象、n 不是整数。按 message 修改后重新提交。
401invalid_api_keyKey 不存在、已删除或已停用,或者账号已停用。到控制台「API Keys」页面检查这把 Key。
402insufficient_quota余额不够预扣这一单。网关先按这一单可能的最高费用预扣,同时发很多请求时也可能出现。如果是并发突发,稍等几秒重试;否则充值。
429rate_limit_exceeded超过了这把 Key 设置的每分钟请求数(按最近 60 秒计)。不带 Retry-After。等几秒再试,或在控制台调高这把 Key 的上限。
503service_unavailable我们这边临时出错,例如保存参考素材失败;/v1/responses 暂时无法处理时也返回 503,并带 Retry-After。稍后重试。

任务失败(status 为 failed)

code什么时候出现怎么办
moderation_blocked图片:模型方的安全审核拒绝了提示词或参考图(也可能是 content_policy_violation)。改写提示词或更换参考图;原样重交通常还会被拒。
upstream_error其他失败:自动重试后仍然失败、排队 15 分钟还没开始、上游拒绝但没有说明原因等,message 写明具体情况。通常重新提交就能成功。

用 Webhook 代替轮询

提交时加上 callback_url,任务一结束(成功或失败),网关就把和查询接口完全一样的结果推送到这个地址,带签名,失败会自动重试。也可以在控制台「设置 → Webhook」里配一个账户级地址。 Webhook 文档 →

curl · callback_url
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"}'