生成影像

用途

根據文字提示生成 AI 影像。可選擇性上傳參考影像，讓生成結果參考其風格或構圖。

方法與路徑

POST /public/v1/generate/image

認證

請參閱認證頁面。需要 Bearer 權杖。

必要標頭：

Authorization: Bearer {your_api_key}

請求欄位

欄位名	類型	必填	說明
prompt	string	是	影像生成的文字提示
ai_model	string	是	使用的 AI 模型。可能的值：GPT Image 1.5, GPT Image 2, GPT Image 2.5 High, GPT Image 2.5 XHigh, Grok Imagine, Grok Imagine Pro, Nano Banana, Nano Banana 2, Nano Banana Pro (deprecated: GPT Image 1.5, Grok Imagine, Grok Imagine Pro, Nano Banana, Nano Banana 2)
ref_images	file[]	否	參考影像檔案 (multipart/form-data)。依 AI 模型不同，最大上傳數量各異

回應

成功回應 (200 OK)：

{
  "job_id": "uuid-string"
}

欄位	類型	說明
job_id	string	已建立作業的唯一識別碼。使用 Get Job Status 查詢結果

錯誤 / 驗證規則

情境	HTTP 狀態	錯誤訊息
Invalid image file	400	"Invalid image file"
Grok Imagine 模型中 ref_images 超過 5 個	400	"The Grok Imagine model supports up to 5 ref_images."
Grok Imagine Pro 模型中 ref_images 超過 1 個	400	"The Grok Imagine Pro model supports up to 1 ref_images."
其他模型中 ref_images 超過 10 個	400	"ref_images supports up to 10 images only"
認證失敗	401	無效的 API 金鑰

參考影像限制：

• GPT Image 1.5: 最多 10 張
• GPT Image 2 / 2.5 High / 2.5 XHigh: 最多 10 張
• Grok Imagine: 最多 5 張
• Grok Imagine Pro: 最多 1 張
• Nano Banana 系列: 最多 10 張

非同步作業行為

此端點建立非同步作業。請求立即回傳 job_id，實際影像生成於背景進行。

輪詢方法：

1. 儲存回應收到的 job_id
2. 輪詢 GET /public/v1/job/{job_id} 確認狀態
3. 狀態變為 Succeed 時，於 image_urls 查看結果

狀態流程： Pending → Succeed 或 Failed

請求範例

cURL (無參考影像)：

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/image" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "prompt=a beautiful sunset over mountains" \
-F "ai_model=GPT Image 1.5"

cURL (包含參考影像)：

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/image" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "prompt=a cat in the style of the reference" \
-F "ai_model=Grok Imagine" \
-F "ref_images=@/path/to/ref1.jpg" \
-F "ref_images=@/path/to/ref2.jpg"