跳到正文

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 出圖分屬兩個價格檔。只有成功完成的任務才計費,提交被拒、審核拒絕與失敗的任務都不計費。

官方牌價見價格頁,你的實際單價以登入後的模型廣場為準,每次請求的實際扣費見用量記錄。

模型規格與官方價也可在模型卡檢視。

下一步