Sprite Zenith
目的
使用 Zenith 流水线生成精灵动画。此功能与 Web 应用「Sprite Zenith」页面相同，并支持其三种模式：
| mode | Web 标签页 | 输入 |
|---|---|---|
image_to_video | 单张图片 | 一张图片 |
first_last_frame | 开始/结束参考图片 | 两张图片：起始帧和结束参考图片，按此顺序 |
video_restyle | Sprite To Sprite | 一个现有精灵（PNG 精灵图 + 网格，或 GIF）以及可选的参考图像 |
代币消耗： 9（36 帧）、25（100 帧）
方法与路径
POST /public/v1/sprite/zenith
认证
请参阅认证页面。需要 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 时才可以为空 |
| frame | integer | 图片模式下必填 | 帧数。允许的值：36、100。在 video_restyle 中必须省略（由源文件推导，见下文） | |
| is_pixel | boolean | 否 | false | 像素风。如果附加图片本身是像素风，请开启此选项。在 video_restyle 中会被忽略（强制为 false） |
| is_prompt_enhancement | boolean | 否 | true | 提示词优化。根据你输入的内容，将提示词优化为更适合生成精灵的形式。在 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）规则
- 源文件： PNG 精灵图（需发送
sprite_grid）或 GIF（不发送sprite_grid）。GIF 最多 120 帧，且时长最多 10 秒。 - 帧数由源文件推导，与 Web 应用完全一致：源文件长度超过 5 秒时生成 100 帧（25 代币），否则生成 36 帧（9 代币）。GIF 使用其实际播放时长；含
N帧的 PNG 精灵图按round(N × 3000 / 36)毫秒计算，因此 61 帧及以上使用 100 帧档位。 - 必须提供
text或reference_image（或两者）。 - 上传源文件的扩展名根据其内容判断，因此即使文件名没有扩展名也能识别出 GIF。
响应
成功响应（200 OK）：
{
"job_id": "uuid-string"
}
| 字段 | 类型 | 说明 |
|---|---|---|
| job_id | string | 已创建任务的唯一标识符。使用 Get Job Status 查询结果 |
错误 / 校验规则
| 情况 | HTTP 状态 | 错误消息 |
|---|---|---|
| 文件不是有效图片或格式不被允许 | 400 | "Invalid image file" |
| 缺少 frame 或值不被允许（图片模式） | 400 | "frame should be one of 36, 100" |
在 video_restyle 中发送了 frame | 400 | "frame is derived from the source for video_restyle; do not send it" |
| 图片数量与模式不符 | 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/zenith" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=image_to_video" \
-F "images=@/path/to/character.png" \
-F "text=running animation cycle" \
-F "frame=36" \
-F "is_pixel=true"
cURL（开始/结束参考图片）：
curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/zenith" \
-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=turn around" \
-F "frame=100"
cURL（Sprite To Sprite，PNG 精灵图 + 网格和参考图像）：
curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/zenith" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=video_restyle" \
-F "images=@/path/to/sprite_sheet.png" \
-F 'sprite_grid={"columns": 6, "rows": 6}' \
-F "reference_image=@/path/to/new_character.png"
cURL（Sprite To Sprite，GIF + 提示词）：
curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/zenith" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=video_restyle" \
-F "images=@/path/to/sprite.gif" \
-F "text=a knight in silver armor"