角色覆蓋 V1

用途

將角色影像覆蓋於精靈圖表上，生成新的精靈圖。用於將角色合成至背景精靈圖表。

方法與路徑

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

認證

請參閱認證頁面。需要 Bearer 權杖。

必要標頭：

Authorization: Bearer {your_api_key}

請求欄位

欄位名	類型	必填	說明
sprite_sheet	file	是	作為參考的精靈圖表影像檔案
character_images	file[]	是	要覆蓋的角色影像檔案。可上傳 1 至 4 個
rows	string	是	包含列資訊的 JSON 字串。每列必須包含 row, title, description
resolution	string	是	輸出解析度。可能的值：1K, 2K, 4K
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"
resolution 值無效	422	1K, 2K, 4K 以外的值會產生 validation error
認證失敗	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/v1" \
-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 "resolution=2K"

cURL (多個角色)：

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/character-overlay/v1" \
-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 "resolution=2K" \
-F "style=pixel"