캐릭터 오버레이 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 | 생성된 작업의 고유 식별자. 작업 상태 조회로 결과를 조회합니다 |
오류 / 유효성 검사 규칙
| 상황 | 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 외의 값은 validation error |
| 인증 실패 | 401 | 유효하지 않은 API 키 |
rows JSON 형식:
[
{
"row": 1,
"title": "Idle",
"description": "Character standing still"
},
{
"row": 2,
"title": "Walk",
"description": "Character walking animation"
}
]
비동기 작업 동작
이 엔드포인트는 비동기 작업을 생성합니다. 요청 즉시 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/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"