特效生成 V1
目的
根据文本描述异步生成特效精灵图。你可以选择上传参考图片来引导特效，并选择输出分辨率和精灵图的背景颜色。此功能与 Web 应用「特效生成」页面的 V1 标签页相同（Web 应用默认打开 V2 标签页）。
代币消耗： 5（1K）、7（2K）、10（4K）
方法与路径
POST /public/v1/generate/effect/v1
认证
请参阅 认证 页面。需要 Bearer 令牌。
必需头信息：
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 | 验证错误 |
异步任务行为
该端点会创建异步任务。请求会立即返回 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"