装备变体
用途
将道具图表中的道具装备到角色基础图片上，并生成装备后的变体。此功能与 Web 应用「装备变体」页面相同。
代币消耗： 5
方法和路径
POST /public/v1/image-tune/equip-variation
认证
请参阅 认证 页面。需要 Bearer 令牌。
必需头信息：
Authorization: Bearer {your_api_key}
请求字段
请以 multipart/form-data 形式发送请求。
| 字段名 | 类型 | 必需 | 说明 |
|---|---|---|---|
| character_image | file | 是 | 角色基础图片（PNG 或 JPEG） |
| item_sheet_image | file | 是 | 道具图表图片（PNG 或 JPEG） |
| prompt | string | 是 | 描述如何装备道具的提示词。空白会被去除，且提示词不能为空 |
响应
成功响应 (200 OK)：
{
"job_id": "uuid-string"
}
| 字段 | 类型 | 说明 |
|---|---|---|
| job_id | string | 创建的作业的唯一标识符。使用 获取作业状态 查询结果 |
错误 / 验证规则
| 情况 | HTTP 状态 | 错误消息 |
|---|---|---|
| 任一图片不是有效的 PNG 或 JPEG 文件 | 400 | "Invalid image file" |
| prompt 为空 | 400 | "prompt must not be empty" |
| 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/image-tune/equip-variation" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "character_image=@/path/to/character.png" \
-F "item_sheet_image=@/path/to/item_sheet.png" \
-F "prompt=equip the iron sword and the leather helmet"