生成特效 V1

用途

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

方法與路徑

POST /public/v1/generate/effect/v1

認證

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

必要標頭：

Authorization: Bearer {your_api_key}

請求欄位

欄位名	類型	必填	說明
description	string	是	要生成的特效文字描述
resolution	string	是	輸出解析度。可能的值：1K, 2K, 4K
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/v1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "description=apply a glowing fantasy aura" \
-F "resolution=1K"

cURL (包含影像)：

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