特效生成 V1
用途
根據文字描述以非同步方式生成特效精靈圖表。可選擇上傳參考圖片來引導特效，並選擇輸出解析度與圖表的背景顏色。此功能與網頁應用程式「特效生成」頁面的 V1 分頁相同（網頁應用程式預設開啟 V2 分頁）。
代幣消耗： 5（1K）、7（2K）、10（4K）
方法與路徑
POST /public/v1/generate/effect/v1
認證
請參閱認證頁面。需要 Bearer Token。
必要標頭：
Authorization: Bearer {your_api_key}
請求欄位
請以 multipart/form-data 傳送請求。
| 欄位名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| description | string | 是 | 特效描述。會移除前後空白 |
| resolution | string | 是 | 解析度。允許的值：1K、2K、4K |
| background_color | string | 是 | 圖表的背景顏色。允許的值：white、chroma_green、magenta、light_gray、light_purple、dark_gray |
| image | file | 否 | 可選的參考圖片（PNG 或 JPEG） |
背景顏色值
| 值 | 標籤 | 顏色 |
|---|---|---|
white | 白色 | #FFFFFF |
chroma_green | 去背綠 | #52FF60 |
magenta | 洋紅 | #FF4CFF |
light_gray | 淺灰 | #A6A6A6 |
light_purple | 淺紫 | #866CFE |
dark_gray | 深灰 | #6A6A6A |
回應
成功回應 (200 OK)：
{
"job_id": "uuid-string"
}
| 欄位 | 類型 | 說明 |
|---|---|---|
| job_id | string | 已建立作業的唯一識別碼。請使用取得作業狀態查詢結果 |
錯誤 / 驗證規則
| 情況 | HTTP 狀態 | 錯誤訊息 |
|---|---|---|
| 圖片不是有效的 PNG 或 JPEG 檔案 | 400 | "Invalid image file" |
| 無效的 API 金鑰 | 401 | "Invalid API key" |
| 欄位遺漏或未知的列舉值 | 422 | Validation error |
非同步作業行為
此端點會建立非同步作業。它會立即回傳 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/effect/v1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "description=apply a glowing fantasy aura" \
-F "resolution=1K" \
-F "background_color=white"
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 "background_color=chroma_green" \
-F "image=@/path/to/input.png"