生成影像
用途
根據文字提示生成 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, Grok Imagine, Grok Imagine Pro, Nano Banana, Nano Banana 2, Nano Banana Pro |
| 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 張
- Grok Imagine: 最多 5 張
- Grok Imagine Pro: 最多 1 張
- Nano Banana 系列: 最多 10 張
非同步作業行為
此端點建立非同步作業。請求立即回傳 job_id，實際影像生成於背景進行。
輪詢方法：
- 儲存回應收到的
job_id - 輪詢
GET /public/v1/job/{job_id}確認狀態 - 狀態變為
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"