特效生成 V2

用途

根據文字描述與所選的幀數，以非同步方式生成特效精靈圖表。可選擇上傳參考圖片，並選擇圖表的背景顏色。此功能與網頁應用程式「特效生成」頁面的 V2 分頁相同（預設分頁）。

代幣消耗： 3

方法與路徑

POST /public/v1/generate/effect/v2

認證

請參閱認證頁面。需要 Bearer Token。

必要標頭：

Authorization: Bearer {your_api_key}

請求欄位

請以 multipart/form-data 傳送請求。

欄位名稱	類型	必填	說明
description	string	是	特效描述。會移除前後空白
frame	integer	是	幀數。允許的值：4、9、16
background_color	string	是	圖表的背景顏色。允許的值：white、chroma_green、magenta、light_gray、light_purple、dark_gray
image	file	否	可選的參考圖片（PNG 或 JPEG）

背景顏色對照表請參閱特效生成 V1。

回應

成功回應 (200 OK)：

{
  "job_id": "uuid-string"
}

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

錯誤 / 驗證規則

情況	HTTP 狀態	錯誤訊息
圖片不是有效的 PNG 或 JPEG 檔案	400	"Invalid image file"
frame 值不允許	400	"frame should be one of 4, 9, 16"
無效的 API 金鑰	401	"Invalid API key"
欄位遺漏或未知的列舉值	422	Validation error

非同步作業行為

此端點會建立非同步作業。它會立即回傳 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 "frame=9" \
-F "background_color=white"

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 "frame=16" \
-F "background_color=magenta" \
-F "image=@/path/to/input.png"