圖片生成介面

共用約定（基礎位址、驗證、回應結構、限流）請見驗證與基礎規範。

建立圖片

POST/v1/images/generations

驗證方式

Authorization: Bearer <API_KEY>，使用於主控台「API 金鑰」建立的平台 API Key。

請求內容 · application/json

Prop

Type

圖片模型對尺寸、數量、傳回格式的限制各不相同，請先使用 /v1/models 確認，並以介面傳回的參數驗證錯誤為準。

請求範例

先使用 /v1/models 確認目前 Key 可用的圖片模型 ID，再把 model 換成它。 size 必須落在該模型支援的級距內——不同模型的最小像素數差異很大，填錯會直接傳回參數錯誤，而不是被無聲降級。

回應可能是網址形式，也可能是 Base64 形式，取決於模型與通道。

請求

curl -X POST "https://locopalai.com/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的图片模型 ID",
  "prompt": "白色桌面上的一个红苹果，柔和自然光，产品摄影",
  "size": "当前模型支持的尺寸",
  "n": 1
}
JSON

回應參數

參數	類型	說明
`created`	integer	生成時間（Unix 秒）
`model`	string	部分模型會傳回實際執行的模型 ID
`data`	array	生成結果清單
`data[].url`	string	圖片位址；以 URL 形式傳回時存在，可能是短期簽名位址
`data[].b64_json`	string	Base64 圖片資料；以 Base64 形式傳回時存在
`data[].size`	string	部分模型會傳回實際生成尺寸
`size`	string	頂層傳回實際生成尺寸，例如 `1024x1024`、`1376x768`
`quality`	string	頂層傳回實際畫質級距，例如 `auto`、`low`
`output_format`	string	頂層傳回實際輸出格式，例如 `png`
`background`	string	頂層傳回背景處理方式，例如 `auto`、`opaque`
`moderation`	string	頂層傳回內容審核級距，部分模型會傳回
`usage`	object	圖片用量；圖生圖會額外統計輸入圖片的 token

單次請求可能只傳回 url 或只傳回 b64_json，取決於模型與通道；請以實際傳回的欄位為準，兩者都存在時優先使用 url。

回應內容

傳回網址（url 形式）：

{
  "created": 1789567052,
  "data": [
    {
      "size": "2048x2048",
      "url": "https://media.example.com/image-public-id.jpeg"
    }
  ],
  "model": "Doubao-Seedream-4.5"
}

傳回 Base64（b64_json 形式，節錄）：

{
  "background": "auto",
  "created": 1789071752,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU..." }
  ]
}

以 url 形式傳回的位址可能是短期簽名位址，請及時轉存或登記；b64_json 形式請自行解碼並妥善存放。不要假設所有圖片模型都接受 response_format 或相同尺寸。實測 gpt-image-1-mini 會拒絕 response_format，Doubao-Seedream-4.5 目前要求圖片至少 3686400 像素，2048x2048 可受理，而 1024x1024 會傳回參數錯誤。

錯誤回應

{
  "error": {
    "message": "当前图片模型不支持请求的尺寸",
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "param": "size"
  }
}

HTTP	回應 / 原因	處理
`400`	`Model name not specified, model name cannot be empty`	請求內容缺少 `model`
`400`	`invalid_parameter`（`param=size`）	改用目前模型支援的尺寸
`400`	`unknown_parameter`（`param=response_format`）	刪除該欄位，使用模型的預設傳回格式
`400`	`InvalidParameter` / `upstream_error`	上游模型拒絕尺寸、像素數或其他參數，請依 `message` 調整
`400`	`invalid_parameter`（`param=n`）	改為 `n=1`
`400`	`image is required`（`code=convert_request_failed`）	圖生圖請求沒有攜帶參考圖片，請依下方範例補上 `image`
`400`	`n must be an integer between 1 and 128`（`code=invalid_request`）	`n` 超出範圍，請改為 `1`–`128`
`429`	`credit_balance_exhausted` / `insufficient_quota`	目前通道餘額不足，請改用其他可用通道或聯絡平台支援
`401`	`Invalid token`	API Key 缺少、錯誤或已失效
`500`	`{"error":{"code":"convert_request_failed","message":"not supported model for image generation, only imagen models are supported"}}`	目前模型不支援圖片生成介面，請改用支援該介面的圖片模型
`503`	`model_not_found` / `No available channel`	目前分組沒有該模型可用的通道，請改選同類模型

完整說明請見錯誤碼與排查。

圖生圖（圖片編輯）

POST/v1/images/edits

在既有圖片的基礎上生成新圖：上傳一張或多張參考圖片，模型會依 prompt 改寫畫面、更換風格或進行局部重繪。

請求內容 · multipart/form-data

Prop

Type

請求必須攜帶參考圖片，缺少時介面會直接傳回參數錯誤，不會進入模型。

請求範例

圖生圖使用 multipart/form-data，以 -F 逐個欄位提交，不要使用 -d。參考圖片透過 image=@檔案路徑 上傳。

需要多張參考圖片時，將欄位寫成陣列形式 image[] 並重複。這裡沒有 JSON 請求內容，Content-Type 由 curl -F 自動設定，不要手動填寫。

圖生圖

curl -X POST "https://locopalai.com/v1/images/edits" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -F "model=从 /v1/models 选择的图片模型 ID" \
  -F "prompt=把这张照片改成柔和的水彩画风格" \
  -F "size=1024x1024" \
  -F "image=@./reference.png"

多張參考圖片時請重複該欄位：

  -F "image[]=@./reference-a.png" \
  -F "image[]=@./reference-b.png"

回應內容

與建立圖片使用相同結構，圖片會以 b64_json 或 url 傳回：

{
  "background": "opaque",
  "created": 1789651524,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU..." }
  ],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 1041,
    "input_tokens_details": { "image_tokens": 1032, "text_tokens": 9 },
    "output_tokens": 439,
    "total_tokens": 1480
  }
}

usage.input_tokens_details.image_tokens 反映參考圖片的消耗：參考圖片越多或尺寸越大，輸入 token 越高。

使用公開網路位址傳送參考圖片

支援參考圖片輸入的模型也可以在 POST /v1/images/generations 的 JSON 請求內容中以 images 傳入，元素為公開網路的 https:// 圖片位址：

curl -X POST "https://locopalai.com/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的图片模型 ID",
  "prompt": "把这张照片改成柔和的水彩画风格",
  "images": ["https://example.com/reference.png"]
}
JSON

參考圖片必須能讓伺服器端直接下載；位址失效或需要登入時，請求會以上游下載錯誤結束。回應結構與建立圖片一致。

與素材庫的關係

圖片生成不會自動進入素材庫。若後續影片任務要把圖片當作參考圖片，請先使用素材庫介面入庫並輪詢到 Active，再以 asset://<asset_id> 參考。

本頁目錄