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