Sprite Zenith
목적
Zenith 파이프라인으로 스프라이트 애니메이션을 생성합니다. 웹 앱의 "Sprite Zenith" 페이지와 동일한 기능이며, 다음 세 가지 모드를 지원합니다:
| mode | 웹 탭 | 입력 |
|---|---|---|
image_to_video | 단일 이미지 | 이미지 1장 |
first_last_frame | 시작/끝 참조 이미지 | 이미지 2장: 시작 프 레임과 끝 참조 이미지, 순서대로 |
video_restyle | Sprite To Sprite | 기존 스프라이트 1개 (PNG 스프라이트 시트 + 그리드, 또는 GIF)와 선택적인 레퍼런스 이미지 |
크레딧 비용: 9 (36프레임), 25 (100프레임)
메서드 및 경로
POST /public/v1/sprite/zenith
인증
인증 페이지를 참고하세요. Bearer 토큰이 필요합니다.
필수 헤더:
Authorization: Bearer {your_api_key}
요 청 필드
요청은 multipart/form-data로 전송합니다. images 필드는 파일마다 한 번씩 반복합니다.
| 필드명 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| mode | string | 예 | 허용 값: image_to_video, first_last_frame, video_restyle | |
| images | file[] | 예 | image_to_video: PNG/JPEG 정확히 1장. first_last_frame: PNG/JPEG 정확히 2장 (시작, 끝). video_restyle: 소스 정확히 1개, PNG 스프라이트 시트 또는 GIF | |
| text | string | 예, 레퍼런스 이미지가 있는 경우 제외 | "" | 움직임을 설명하는 프롬프트. 공백은 제거됩니다. video_restyle에서는 reference_image가 주어진 경우에만 비어 있을 수 있습니다 |
| frame | integer | 이미지 모드에서는 예 | 프레임. 허용 값: 36, 100. video_restyle에서는 생략해야 합니다 (소스에서 도출, 아래 참고) | |
| is_pixel | boolean | 아니오 | false | 픽셀아트. 첨부한 이미지가 픽셀아트 기반의 이미지라면 켜주세요. video_restyle에서는 무시됩니다 (강제로 false) |
| is_prompt_enhancement | boolean | 아니오 | true | 프롬프트 보정. 입력한 내용을 기반으로 스프라이트 생성에 적합하게 다듬어요. video_restyle에서는 무시됩니다 (강제로 false) |
| reference_image | file | 아니오 (video_restyle 전용) | 레퍼런스 이미지 (선택). PNG만 가능. 소스 스프라이트의 대상이 이 이미지로 교체됩니다 | |
| sprite_grid | string | PNG 시트를 사용하는 video_restyle | PNG 시트를 자르는 방식을 설명하는 JSON 객체, 예: {"columns": 6, "rows": 6}. 각 값은 1–32, 최대 120프레임. GIF 소스에서는 허용되지 않습니다 |
Sprite To Sprite (video_restyle) 규칙
- 소스 파일: PNG 스프라이트 시트(
sprite_grid전송) 또는 GIF(sprite_grid없음). GIF는 최대 120프레임, 최대 10초 길이여야 합니다. - 프레임 수는 소스에서 도출되며, 웹 앱과 정확히 동일하게 동작합니다: 소스가 5초보다 길면 100프레임(25 크레딧), 그렇지 않으면 36프레임(9 크레딧)을 생성합니다. GIF는 실제 재생 길이를 사용하고,
N프레임의 PNG 시트는round(N × 3000 / 36)ms로 계산되므로 61프레임 이상이면 100프레임 등급을 사용합니다. text또는reference_image(또는 둘 다)를 반드시 제공해야 합니다.- 업로드된 소스의 파일 확장자는 내용에서 판별되므로, 파일명에 확장자가 없어도 GIF가 감지됩니다.
응답
성공 응답 (200 OK):
{
"job_id": "uuid-string"
}
| 필드 | 타입 | 설명 |
|---|---|---|
| job_id | string | 생성된 작업의 고유 식별자. 작업 상태 조회로 결과를 조회합니다 |
오류 / 유효성 검사 규칙
| 상황 | HTTP 상태 | 에러 메시지 |
|---|---|---|
| 파일이 유효한 이미지가 아니거나 허용되지 않는 형식임 | 400 | "Invalid image file" |
| frame 누락 또는 허용되지 않는 값 (이미지 모드) | 400 | "frame should be one of 36, 100" |
video_restyle에서 frame 전송 | 400 | "frame is derived from the source for video_restyle; do not send it" |
| 모드에 맞지 않는 이미지 개수 | 400 | "image_to_video requires exactly one image" / "first_last_frame requires exactly two images (start, end)" / "video_restyle requires exactly one source image (PNG sprite sheet or GIF)" |
| text가 비어 있음 (이미지 모드) | 400 | "text must not be empty" |
text가 비어 있고 레퍼런스 이미지 없음 (video_restyle) | 400 | "video_restyle requires text when no reference_image is given" |
video_restyle 외에서 reference_image 또는 sprite_grid 전송 | 400 | "reference_image is only supported for video_restyle" / "sprite_grid is only supported for video_restyle" |
| sprite_grid 없는 PNG 시트 | 400 | "sprite_grid is required for a PNG sprite sheet" |
| sprite_grid가 있는 GIF | 400 | "sprite_grid is not allowed for a GIF source" |
| sprite_grid 형식 오류 또는 범위 초과 | 400 | sprite_grid must be a JSON object like {"columns": 6, "rows": 6} (1-32 each, at most 120 frames) |
| GIF가 120프레임을 초과함 | 400 | "GIF must have at most 120 frames" |
| GIF가 10초보다 김 | 400 | "GIF must be at most 10 seconds long" |
| 유효하지 않은 API 키 | 401 | "Invalid API key" |
| 필드 누락 또는 알 수 없는 mode | 422 | Validation error |
모든 유효성 검사는 파일이 업로드되기 전에 실행됩니다.
비동기 작업 동작
이 엔드포인트는 비동기 작업을 생성합니다. 요청 즉시 job_id를 반환하고, 실제 스프라이트 생성은 백그라운드에서 진행됩니다.
폴링 방법:
- 응답으로 받은
job_id를 저장합니다 GET /public/v1/job/{job_id}를 폴링하여 상태를 확인합니다- 상태가
Succeed가 되면image_urls에서 결과를 확인합니다 (스프라이트 시트 및 GIF)
상태 흐름: Pending → Succeed 또는 Failed
요청 예시
cURL (단일 이미지):
curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/zenith" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=image_to_video" \
-F "images=@/path/to/character.png" \
-F "text=running animation cycle" \
-F "frame=36" \
-F "is_pixel=true"
cURL (시작/끝 참조 이미지):
curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/zenith" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=first_last_frame" \
-F "images=@/path/to/start.png" \
-F "images=@/path/to/end.png" \
-F "text=turn around" \
-F "frame=100"
cURL (Sprite To Sprite, 그리드와 레퍼런스 이미지가 있는 PNG 시트):
curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/zenith" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=video_restyle" \
-F "images=@/path/to/sprite_sheet.png" \
-F 'sprite_grid={"columns": 6, "rows": 6}' \
-F "reference_image=@/path/to/new_character.png"
cURL (Sprite To Sprite, 프롬프트가 있는 GIF):
curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/zenith" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=video_restyle" \
-F "images=@/path/to/sprite.gif" \
-F "text=a knight in silver armor"