Sprite Pulsar
目的
使用 Pulsar 流水线生成 36 帧的精灵动画。此功能与 Web 应用「Sprite Pulsar」页面相同。它使用与 Sprite Zenith 相同的输入和模式，但长度固定为 36 帧，且没有提示词优化选项。
| mode | Web 标签页 | 输入 |
|---|---|---|
image_to_video | 单张图片 | 一张图片 |
first_last_frame | 开始/结束 参考图片 | 两张图片：起始帧和结束参考图片，按此顺序 |
video_restyle | Sprite To Sprite | 一个现有精灵（PNG 精灵图 + 网格，或 GIF）以及可选的参考图像 |
代币消耗： 3（image_to_video、first_last_frame）、4（video_restyle）
方法与路径
POST /public/v1/sprite/pulsar
认证
请参阅认证页面。需要 Bearer Token。
必需请求头：
Authorization: Bearer {your_api_key}
请求字段
请以 multipart/form-data 形式发送请求。每个文件重复发送一次 images 字段。
| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| mode | string | 是 | 允许的值：image_to_video、first_last_frame、video_restyle | |
| images | file[] | 是 | image_to_video：恰好 1 个 PNG/JPEG。first_last_frame：恰好 2 个 PNG/JPEG（起始、结束）。video_restyle：恰好 1 个源文件，PNG 精灵图或 GIF | |
| text | string | 是，提供参考图像时除外 | "" | 描述动作的提示词。空白会被去除。在 video_restyle 中，仅当提供了 reference_image 时才可以为空 |
| is_pixel | boolean | 否 | false | 像素风。如果附加图片本身是像素风，请开启此选项。在 video_restyle 中会被忽略（强制为 false） |
| reference_image | file | 否（仅 video_restyle） | 参考图像（可选）。仅支持 PNG。源精灵的主体会被替换为此图片 | |
| sprite_grid | string | video_restyle 使用 PNG 精灵图时 | 描述 PNG 精灵图切分方式的 JSON 对象，例如 {"columns": 6, "rows": 6}。每个值 1–32，最多 120 帧。使用 GIF 源文件时不允许 |
Sprite To Sprite（video_restyle）的源文件规则与 Sprite Zenith 相同：PNG 精灵图 + sprite_grid，或最多 120 帧且不超过 10 秒的 GIF。没有 frame 字段；输出始终为 36 帧。
响应
成功响应（200 OK）：
{
"job_id": "uuid-string"
}
| 字段 | 类型 | 说明 |
|---|---|---|
| job_id | string | 已创建任务的唯一标识符。使用 Get Job Status 查询结果 |
错误 / 校验规则
| 情况 | HTTP 状态 | 错误消息 |
|---|---|---|
| 文件不是有效图片或格式不被允许 | 400 | "Invalid image file" |
| 图片数量与模式不符 | 400 | "image_to_video requires exactly one image" / "first_last_frame requires exactly two images (start, end)" / "video_restyle requires exactly one source image (PNG sprite sheet or GIF)" |
| text 为空（图片模式） | 400 | "text must not be empty" |
text 为空且没有参考图像（video_restyle） | 400 | "video_restyle requires text when no reference_image is given" |
在 video_restyle 之外发送了 reference_image 或 sprite_grid | 400 | "reference_image is only supported for video_restyle" / "sprite_grid is only supported for video_restyle" |
| PNG 精灵图未提供 sprite_grid | 400 | "sprite_grid is required for a PNG sprite sheet" |
| GIF 附带了 sprite_grid | 400 | "sprite_grid is not allowed for a GIF source" |
| sprite_grid 格式错误或超出范围 | 400 | sprite_grid must be a JSON object like {"columns": 6, "rows": 6} (1-32 each, at most 120 frames) |
| GIF 超过 120 帧 | 400 | "GIF must have at most 120 frames" |
| GIF 超过 10 秒 | 400 | "GIF must be at most 10 seconds long" |
| API Key 无效 | 401 | "Invalid API key" |
| 缺少字段或 mode 未知 | 422 | 校验错误 |
所有校验都会在上传任何文件之前执行。
异步任务行为
此端点会创建异步任务。它会立即返回 job_id，实际的精灵生成会在后台进行。
轮询方法：
- 保存响应中收到的
job_id - 轮询
GET /public/v1/job/{job_id}检查状态 - 当状态变为
Succeed时，在image_urls中查看结果（精灵图和 GIF）
状态流： Pending → Succeed 或 Failed
请求示例
cURL（单张图片）：
curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/pulsar" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=image_to_video" \
-F "images=@/path/to/character.png" \
-F "text=idle breathing" \
-F "is_pixel=true"
cURL（开始/结束参考图片）：
curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/pulsar" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=first_last_frame" \
-F "images=@/path/to/start.png" \
-F "images=@/path/to/end.png" \
-F "text=draw the sword"
cURL（Sprite To Sprite，GIF + 参考图像）：
curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/pulsar" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=video_restyle" \
-F "images=@/path/to/sprite.gif" \
-F "reference_image=@/path/to/new_character.png"