角色叠加 V2

用途

在精灵表上叠加角色图像以生成新的精灵。用于将角色合成到背景精灵表中。

方法和路径

POST /public/v1/sprite/character-overlay/v2

认证

请参阅 认证 页面。需要 Bearer 令牌。

必需头信息：

Authorization: Bearer {your_api_key}

请求字段

字段名	类型	必需	说明
sprite_sheet	file	是	作为参考的精灵表图像文件
character_images	file[]	是	要叠加的角色图像文件。可上传 1 到 4 个
rows	string	是	包含行信息的 JSON 字符串。每行必须包含 row, title, description
quality	string	是	质量。可能的值: standard, pro
style	string	否	风格指定 (可选)。可用值：pixel, cartoon, sd, quater_view

响应

成功响应 (200 OK)：

{
  "job_id": "uuid-string"
}

字段	类型	说明
job_id	string	创建的作业的唯一标识符。使用 Get Job Status 查询结果

错误 / 验证规则

情况	HTTP 状态	错误消息
Invalid image file	400	"Invalid image file"
character_images 少于 1 个或超过 4 个	400	"character_images must contain between 1 and 4 files"
缺少 character_images 字段	422	Field required
rows 不是有效的 JSON	400	"rows must be a valid JSON list"
rows 不是列表	400	"rows must be a JSON list"
行中缺少必需键	400	"each row must be an object with row, title, description"
row 不是整数	400	"row must be an integer"
title 或 description 不是字符串	400	"title and description must be strings"
quality 值无效	422	standard, pro 以外的值会导致验证错误
认证失败	401	无效的 API 密钥

rows JSON 格式：

[
  {
    "row": 1,
    "title": "Idle",
    "description": "Character standing still"
  },
  {
    "row": 2,
    "title": "Walk",
    "description": "Character walking animation"
  }
]

异步作业行为

此端点创建异步作业。请求立即返回 job_id，实际叠加作业在后台进行。

轮询方法：

1. 保存响应中收到的 job_id
2. 轮询 GET /public/v1/job/{job_id} 检查状态
3. 当状态变为 Succeed 时，从 image_urls 查看结果

状态流程： Pending → Succeed 或 Failed

请求示例

cURL (单个角色)：

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/character-overlay/v2" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "sprite_sheet=@/path/to/background_sprite.png" \
-F "character_images=@/path/to/character.png" \
-F 'rows=[{"row":1,"title":"Idle","description":"Standing"},{"row":2,"title":"Walk","description":"Walking"}]' \
-F "quality=standard"

cURL (像素风格 + 多个角色)：

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/character-overlay/v2" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "sprite_sheet=@/path/to/background_sprite.png" \
-F "character_images=@/path/to/char1.png" \
-F "character_images=@/path/to/char2.png" \
-F "character_images=@/path/to/char3.png" \
-F 'rows=[{"row":1,"title":"Scene1","description":"First scene"},{"row":2,"title":"Scene2","description":"Second scene"}]' \
-F "quality=pro" \
-F "style=pixel"