精靈換膚 V1

用途

變更現有精靈圖影像的外觀，生成新風格的精靈圖。用於改變角色外觀或轉換為不同風格。

方法與路徑

POST /public/v1/sprite/reskin/v1

認證

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

必要標頭：

Authorization: Bearer {your_api_key}

請求欄位

欄位名	類型	必填	說明
image	file	是	要重製外觀的原始精靈圖影像檔案
description	string	是	描述將套用到精靈圖上的變更內容
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"
resolution 值無效	422	1K, 2K, 4K 以外的值會產生 validation error
style 值無效	422	pixel, cartoon, sd, quater_view 以外的值會產生 validation error
認證失敗	401	無效的 API 金鑰

風格選項：

• pixel: 像素藝術風格
• cartoon: 卡通風格
• sd: SD (Standard Definition) 風格
• quater_view: 四分之一視角 (isometric) 風格

非同步作業行為

此端點建立非同步作業。請求立即回傳 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/reskin/v1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "image=@/path/to/sprite.png" \
-F "description=change the warrior character armor to golden" \
-F "resolution=2K"

cURL (指定像素風格)：

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/reskin/v1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "image=@/path/to/sprite.png" \
-F "description=convert the character to pixel art style" \
-F "resolution=1K" \
-F "style=pixel"