圖片生成 API

使用目前 Essevin To C 密鑰可用的 GPT Image 與 Gemini 圖片模型生成或編輯圖片。

Essevin 為目前密鑰已經開放的圖片模型提供統一的 OpenAI Images 兼容請求結構。請先查詢完整模型 ID，不要假設完整模型目錄裡的每一種圖片模型都可用。

項目	填寫值
Base URL	`https://api.essevin.com/v1`
圖片生成	`POST /v1/images/generations`
圖片編輯	返回模型能力包含編輯時使用 `POST /v1/images/edits`
異步狀態	收到 `202 Accepted` 後使用 `GET /v1/images/tasks?task_id=...`
鑑權	`Authorization: Bearer <對應套餐密鑰>`

1. 查詢已開放的圖片模型

curl https://api.essevin.com/v1/models \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY"

從返回結果中選擇帶圖片能力的完整 ID。代表型號包括 gpt-image-2、gemini-2.5-flash-image 和 gemini-3-pro-image；實際開放範圍由密鑰分組決定。

2. 生成一張圖片

curl https://api.essevin.com/v1/images/generations \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "白色桌面上的陶瓷杯，乾淨的商品攝影",
    "size": "1024x1024",
    "n": 1,
    "response_format": "url"
  }'

響應裡的圖片 URL 只在有限時間內有效。需要長期保留時，請及時下載到項目現有儲存。

參考圖與圖片編輯

不同模型的圖片能力不完全相同。先檢查 GET /v1/models，再只使用所選路由支持的欄位：

輸入方式	用途
在 generation JSON 中傳 `image` URL 或 Data URL	模型支持時進行圖生圖或參考圖生成
`/v1/images/edits` multipart 請求	模型支持時復用已有 OpenAI 編輯代碼
`prompt`	描述要修改的內容，以及必須保持不變的細節

用 multipart 編輯本地圖片

curl https://api.essevin.com/v1/images/edits \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=把杯子移到右側，並保持標籤文字不變" \
  -F "[email protected]" \
  -F "size=1536x1024" \
  -F "quality=medium" \
  -F "output_format=png"

Gemini 圖片兼容行為

Gemini 圖片模型繼續使用相同的 OpenAI Images 客戶端協議，但模型能力不一定與 GPT Image 完全一致。

能力	行為
請求	調用 `/v1/images/generations`；Essevin 會按所選 Gemini 模型適配請求。
響應	從標準 OpenAI Images JSON 的 `data[].b64_json` 或 `data[].url` 讀取結果。
編輯	支持編輯的模型可通過 `/v1/images/edits` 接收一張或多張參考圖；Gemini 不支持硬區域 `mask`。
尺寸	閘道會在生成前按所選模型校驗 `size`。
可選欄位	`quality`、`background`、`output_format`、`input_fidelity` 與 `n` 是否生效取決於模型。
流式	Gemini 圖片請求保持同步，不要發送 `stream: true`。
異步	部分模型支持 `Prefer: respond-async`；請按 HTTP 狀態區分 `202 task_id` 與同步結果。

所選圖片模型屬於 Gemini 套餐分組時，請使用 ESSEVIN_GEMINI_API_KEY。包括後綴在內的完整模型 ID 必須與 GET /v1/models 返回值完全一致。

常用請求欄位

欄位	是否必填	說明
`model`	是	目前密鑰返回的完整 GPT Image 或 Gemini 圖片模型 ID
`prompt`	是	圖片內容、構圖、風格、文字或編輯要求
`size`	否	`auto` 或 `寬x高`；支持範圍取決於模型
`quality`	否	模型支持時可用 `low`、`medium`、`high` 或 `auto`
`n`	否	生成張數；部分模型只支持 `1`
`background`	否	模型支持時可用 `opaque` 或 `transparent`
`output_format`	否	模型支持時可用 `png`、`jpeg` 或 `webp`
`image` / `mask`	編輯時使用	可傳一張或多張參考圖；`mask` 取決於模型，Gemini 不支持

不支持的尺寸或欄位應在生成前返回校驗錯誤。遇到 400 時，請對照所選模型能力修改請求，不要盲目重試。

響應模式

同步響應

不傳 Prefer: respond-async 時，請求會等待生成完成並返回標準 OpenAI Images JSON。部分模型返回 base64，部分模型返回臨時 URL。

{
  "created": 1780000000,
  "data": [{
    "b64_json": "iVBORw0KGgoAAA...",
    "revised_prompt": "..."
  }],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 1056,
    "total_tokens": 1074
  }
}

非 Gemini 圖片模型只有在明確支持時才可使用 stream: true 獲取 Images SSE；最後一個 data: 事件包含 Images JSON，隨後是 [DONE]。官方 SDK 與 Gemini 圖片請求應保持默認同步模式。

異步任務響應

對於支持異步的模型，發送 Prefer: respond-async。202 Accepted 響應會包含 task_id 與 status_url；輪詢到 completed 或 failed。模型也可能直接同步返回，因此必須按實際 HTTP 狀態分支處理。

# 提交請求，並檢查 HTTP 狀態與 task_id。
curl -i https://api.essevin.com/v1/images/generations \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "夜晚的電影感未來城市",
    "size": "2048x2048"
  }'

# 只有第一步返回 202 和 task_id 後才輪詢。
curl "https://api.essevin.com/v1/images/tasks?task_id=your-task-id" \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY"

第一次驗證保持最小成本

只生成一張最低可用解析度的測試圖。不要記錄 API 密鑰、完整 Data URL、私有原圖或完整 base64 輸出。

商品素材發佈前，請逐張檢查標籤、Logo、包裝文字、商品比例以及畫面中的人物細節。

本頁目錄