キャラクターオーバーレイ V1

Purpose

スプライトシート上にキャラクター画像をオーバーレイし、新しいスプライトを生成します。背景スプライトシートにキャラクターを合成する際に使用します。

Method and Path

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

Authentication

認証ページを参照してください。Bearerトークンが必要です。

必須ヘッダー:

Authorization: Bearer {your_api_key}

Request Fields

フィールド名	タイプ	必須	説明
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

Response

成功レスポンス (200 OK):

{
  "job_id": "uuid-string"
}

フィールド	タイプ	説明
job_id	string	作成されたジョブの一意識別子。Get Job Statusで結果を照会します

Error / Validation Rules

状況	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"
  }
]

Async Job Behavior

このエンドポイントは非同期ジョブを作成します。リクエスト即座にjob_idを返し、実際のオーバーレイジョブはバックグラウンドで進行します。

ポーリング方法:

1. レスポンスで受け取ったjob_idを保存します
2. GET /public/v1/job/{job_id}をポーリングして状態を確認します
3. 状態がSucceedになるとimage_urlsで結果を確認します

状態フロー: Pending → Succeed または Failed

Example Request

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"