特效生成 V2

目的

非同步生成特效風格的結果。你可以提供文字描述來引導特效生成，並可選擇上傳影像。

方法與路徑

POST /public/v1/generate/effect/v2

認證

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

必要標頭：

Authorization: Bearer {your_api_key}

請求欄位

欄位名稱	類型	必填	說明
description	string	是	特效描述
quality	string	是	輸出品質：standard, pro
frame	number	是	影格數：4, 9, 16
image	file	否	可選參考圖片

回應

成功回應 (200 OK)：

{
  "job_id": "uuid-string"
}

欄位	類型	說明
job_id	string	建立的作業唯一識別碼。使用 取得作業狀態 查詢結果

錯誤 / 驗證規則

情況	HTTP 狀態	錯誤訊息
Invalid image file	400	"Invalid image file"
API 金鑰無效	401	Invalid API key

非同步工作行為

此端點會建立非同步工作。請求會立即回傳 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/effect/v2" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "description=apply a glowing fantasy aura" \
-F "quality=standard" \
-F "frame=4"

cURL (包含圖片)：

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/effect/v2" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "description=apply a neon cyberpunk effect" \
-F "quality=pro" \
-F "frame=16" \
-F "image=@/path/to/input.png"