跳到正文

Midjourney

用 Midjourney 异步生成图片:参数、返回与注意事项。

项目值
Base URLhttps://api.hop-base.com/v1
提交任务POST /v1/images/generations
查询任务GET /v1/video/tasks/{task_id}
任务列表GET /v1/video/tasks
密钥分组「Midjourney 生图分组」

Midjourney 是异步接口:提交任务拿到 HopBase 任务 ID,再轮询结果;每个任务固定出四张图,每张都计费。

可用型号

型号模型 ID档位/尺寸官方价
Midjourney v8.2midjourney-v8-2默认 1K;--hd 原生 2K$0.0067起/ 张

正式发起付费任务前,先用 GET /v1/models 确认密钥可用的准确模型 ID。

请求参数

所有请求使用 Authorization: Bearer sk-你的密钥 和 Content-Type: application/json。尺寸、画质等都写在 prompt 末尾的 -- 参数里,不是请求字段。

请求体字段

参数必填类型与限制默认说明
model必填字符串,精确匹配—midjourney-v8-2
prompt必填字符串,须有画面描述—可在描述后加 -- 参数
images可选数组,0–1 项—参考图
n可选只能是 44每个任务固定四张
quality请省略必须为空—要 2K 用 --hd
extra请省略必须为空—不接受额外参数
  • prompt 必须有画面描述,不能只有 -- 参数,也不能含 ::;只传图片、没有描述会被拒绝。
  • images 是参考图,例如 [{"url":"https://example.com/ref.png"}]。只能放 1 张;要用多张见下方「多张参考图」。
  • images[] 每项 url(公网绝对 HTTP(S) 地址)/ file_id 二选一,不能带 usage。
  • quality 非空返回 400;要 2K 请在 prompt 写 --hd。
  • extra 非空对象返回 400,这个模型不接受额外参数。
只接受上表字段,其他字段一律 400:

请求体按严格 JSON 解析,表外的任何字段都会在提交时直接返回 400,任务不会创建、也不计费。画幅请写在提示词里的 --ar,画质用 --hd。

OpenAI Images 习惯带的 size、response_format、style 等都属于表外字段,完整清单见下方「注意事项」的「更多细节」。

尺寸与画幅比例

图片尺寸由提示词里的 --ar(也可写作 --aspect)决定。--hd 会以大约两倍的边长原生出图。

任意正整数比例都可以用,不限于下表——只要横竖两个方向都不超过 14:1(加 --hd 时为 4:1)。下表列出常用比例,尺寸均为实测值,不是换算得出的——--hd 并不是精确的两倍。

--ar默认加 --hd
1:1(默认)1024 × 10242048 × 2048
1:2768 × 15361552 × 3104
9:16816 × 14561648 × 2944
2:3896 × 13441792 × 2688
3:4928 × 12321904 × 2544
5:6992 × 12002016 × 2416
6:51200 × 9922416 × 2016
4:31232 × 9282544 × 1904
3:21344 × 8962688 × 1792
16:91456 × 8162944 × 1648
2:11536 × 7683104 × 1552
21:91680 × 7203376 × 1440
14:14096 × 288拒绝——见下文
  • --ar 必须带且只带一个 宽:高 形式的值,两边都是正整数,--ar 1.5:1 会被拒绝。
  • 横竖两个方向的比例都不得超过 14:1。
  • --hd 会把这个上限压到 4:1:--hd --ar 14:1 会被拒绝,--hd --ar 4:1 出图 4096 × 1184。

提示词参数

下列参数会被接受并透传:

参数取值范围用途
--ar / --aspect整数比画幅比例
--hd开关原生 2K 出图
--s / --stylize0-1000风格化强度
--c / --chaos0-100四张图之间的差异度
--weird / --w0-3000非常规美学
--iw0-3参考图权重
--sref + --sw--sw 0-1000风格参考及其强度
--no文本排除元素
--seed整数复现结果
--tile、--exp开关 / 0-100无缝平铺;动态范围
  • 请把所有参数写在描述之后:第一个 -- 参数之后的文字都会被当作参数的值。
  • 带取值范围的数值参数必须紧跟且只跟一个数字,缺值、多值、非数字或超出范围都返回 400。

多张参考图

images 只能放 1 张。要用多张,把图片 URL 用空格隔开写在 prompt 最前面,后面再接画面描述——这是 Midjourney 官方的 Image Prompt 写法:

"prompt": "https://example.com/a.png https://example.com/b.png a cat sitting in a vintage car --ar 1:1"

  • 每个 URL 都必须是公开可访问的 HTTP(S) 地址。
  • 参考图是灵感来源,不是拼贴:几张图的影响力不会平均分配,某张图里主体特别鲜明时可能压过其他图。
  • 想让某张图里的元素一定出现,请在描述里写明,或用 --iw(0-3)提高参考图的权重。

不接受的参数

下列参数在提交时直接返回 400。官方要么静默忽略它们,让你为没生效的效果付钱;要么在几分钟后把任务判失败。

参数原因
--q / --quality在这个模型版本上没有效果
--nijiNiji 是另一个模型版本,不是这里的参数
--repeat没有效果;每个任务的出图张数是固定的
--oref、--crefv8.x 上没有 Omni 参考与角色参考
--stealth、--stop这个模型版本不支持
--relax、--turbo任务一律以 Fast 模式运行:本接口不提供 Relax,v8.x 不支持 Turbo
--draft每个任务会返回 24 张低分辨率图;不提供
--profile / --p本接口不支持个性化配置档
::这个模型版本不支持多段提示词权重

返回结果

提交响应

提交成功返回 HTTP 202:

字段类型说明
idstringHopBase 任务 ID,用于查询
objectstring固定为 image.generation.task
modelstringmidjourney-v8-2
statusstring初始为 queued
createdinteger创建时间(Unix 秒)
billing_bucketstring按默认档还是 --hd 2K 档计价
requested_imagesinteger固定为 4
images_per_taskinteger固定为 4
noticestring固定四张、每张计费的提示
{
  "id": "ktEXAMPLE",
  "object": "image.generation.task",
  "model": "midjourney-v8-2",
  "status": "queued",
  "created": 1790000000,
  "billing_bucket": "img_1k",
  "requested_images": 4,
  "images_per_task": 4,
  "notice": "this model always returns 4 images per task and bills every returned image"
}

查询结果

status 依次经过 queued → processing → completed 或 failed。只有后两者是终态,其他任何值都按进行中处理。

字段类型说明
idstring任务 ID
objectstring固定为 video.generation.task,生图任务也一样
statusstringqueued / processing / completed / failed
outputsstring[]完成后带四个图片地址,24 小时有效
usageobject完成后的计量:bucket(即提交时的计费档位)与 billed_images(固定为 4)
usage.costnumber本任务扣费的人民币金额(与 usage.cost_usd 为同一笔扣费)
usage.cost_usdnumber本任务实际从余额扣除的美元金额,与使用记录相同
usage.currencystringusage.cost 的币种,恒为 CNY
error.codestring失败时的稳定错误码
error.messagestring失败原因的英文说明

下例为已完成任务的结构节选,ID 与 URL 为示意值:

{
  "id": "ktEXAMPLE",
  "object": "video.generation.task",
  "model": "midjourney-v8-2",
  "status": "completed",
  "created": 1790000000,
  "outputs": [
    "https://api.hop-base.com/example-signed-image-1.png",
    "https://api.hop-base.com/example-signed-image-2.png",
    "https://api.hop-base.com/example-signed-image-3.png",
    "https://api.hop-base.com/example-signed-image-4.png"
  ],
  "usage": { "bucket": "img_1k", "billed_images": 4, "cost": 0.1496, "cost_usd": 0.022, "currency": "CNY" }
}

输出地址在 api.hop-base.com 域名下,是自任务完成起 24 小时有效的签名链接。再次查询返回同一地址、不会续期,过期访问返回 410,请在有效期内下载保存。

任务结束后,查询响应根对象的 usage 还会带 cost_usd(本任务从余额实际扣除的美元金额,未扣费的失败为 0)、cost(同一笔的人民币金额)与 currency(恒为 CNY),详见视频生成。任务列表(GET /v1/video/tasks)里每个终态任务的 usage 也带同样的 cost、cost_usd 与 currency。

示例

提交一个 16:9 任务,再轮询到终态:

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "midjourney-v8-2",
    "prompt": "a red apple on a wooden table, studio light --ar 16:9"
  }'

# 用返回的 id 查询,不要传计费标头
curl https://api.hop-base.com/v1/video/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-你的密钥"

注意事项

  • 每个任务固定出四张图、每张都计费,请按每次提交四张图来做预算。
  • n 只接受 4 或整个省略。
  • 画幅写 --ar、2K 写 --hd,请求体里带 size 或 quality 都会返回 400。
  • 带 --hd 时画幅上限从 14:1 降到 4:1。
  • 所有 -- 参数都写在画面描述之后。
  • 并发很有限,并行提交一大批任务只会让多数失败,而不是排队等待。
  • 创建 2 小时后仍未结束的任务会被判为失败,不计费。
内容审核较严格:

即使是时尚、商业类人像,对人物身材、体型、腿部等身体部位的细致描写或对贴身、轻薄服装的强调,叠加在一起时也可能被判定不通过。建议改为描述整体造型、风格、场景和光线后再提交。

常见报错

提交阶段的错误都是 HTTP 400,任务不会创建、不计费。网关按顺序检查,遇到第一处错误即返回,响应体结构:

{
  "error": {
    "message": "request body does not match the JSON contract: json: unknown field \"size\"",
    "type": "invalid_request_error"
  }
}
报错改法
json: unknown field "size"删掉表外字段,画幅写 --ar
the quality field has no effect on this model删掉 quality,2K 写 --hd
the n field cannot change that省略 n 或设为 4
prompt must contain a description在参数前补上画面描述
parameter --draft is not accepted删掉不接受的参数
may not exceed 4:1 when --hd is used缩小比例,或去掉 --hd

任务失败

任务失败时,查询接口仍返回 HTTP 200,status 为 failed。请按 status 判断成败,按 error.code 分支处理,并展示 error.message。

原因error.code建议
提示词未通过内容审核input_sensitive改写提示词后重新提交
参考图未通过内容审核input_sensitive换一张参考图后重新提交
审核未通过(未说明是哪一项)input_sensitive改写提示词;带了参考图就一并更换
并发已满rate_limited稍后重试,减少同时在跑的任务
缺少描述prompt_required补上画面描述
参数不被支持invalid_request删除提示词末尾不在支持列表里的参数
画幅比例无效invalid_request改用整数比例,遵守上限
提示词格式错误invalid_request检查末尾参数的写法与取值
生成失败(其他原因)generation_failed可原样重试一次;仍失败请带任务 ID 联系支持
任务无法追踪generation_failed带任务 ID 联系支持
超时timeout重新提交
结束但没有产出no_output重新提交

计费

按返回的图片张数计费,一个任务按所在档位的单价收四张图的费用;默认出图与 --hd 2K 出图分属两个价格档。只有成功完成的任务才计费,提交被拒、审核拒绝与失败的任务都不计费。

官方牌价见价格页,你的实际单价以登录后的模型广场为准,每次请求的实际扣费见用量记录。

模型规格与官方价也可在模型卡查看。

下一步