이펙트 생성 V1
목적
텍스트 설명을 기반으로 이펙트 스프라이트 시트를 비동기적으로 생성합니다. 선택적으로 참조 이미지를 업로드해 이펙트를 안내할 수 있으며, 출력 해상도와 시트의 배경 색상을 선택할 수 있습니다. 웹 앱 "이펙트 생성" 페이지의 V1 탭과 동일한 기능입니다 (웹 앱은 기본적으로 V2 탭으로 열립니다).
크레딧 비용: 5 (1K), 7 (2K), 10 (4K)
메서드 및 경로
POST /public/v1/generate/effect/v1
인증
인증 페이지를 참고하세요. Bearer 토큰이 필요합니다.
필수 헤더:
Authorization: Bearer {your_api_key}
요청 필드
요청은 multipart/form-data로 전송합니다.
| 필드명 | 타입 | 필수 | 설 명 |
|---|---|---|---|
| description | string | 예 | 이펙트 설명. 앞뒤 공백은 제거됩니다 |
| resolution | string | 예 | 해상도. 허용 값: 1K, 2K, 4K |
| background_color | string | 예 | 시트의 배경 색상. 허용 값: white, chroma_green, magenta, light_gray, light_purple, dark_gray |
| image | file | 아니오 | 선택적 참조 이미지 (PNG 또는 JPEG) |
배경 색상 값
| 값 | 라벨 | 색상 |
|---|---|---|
white | 화이트 | #FFFFFF |
chroma_green | 크로마키 그린 | #52FF60 |
magenta | 마젠타 | #FF4CFF |
light_gray | 라이트그레이 | #A6A6A6 |
light_purple | 라이트퍼플 | #866CFE |
dark_gray | 다크그레이 | #6A6A6A |
응답
성공 응답 (200 OK):
{
"job_id": "uuid-string"
}
| 필드 | 타입 | 설명 |
|---|---|---|
| job_id | string | 생성된 작업의 고유 식별자. 작업 상태 조회로 결과를 조회합니다 |
오류 / 유효성 검사 규칙
| 상황 | HTTP 상태 | 에러 메시지 |
|---|---|---|
| 이미지가 유효한 PNG 또는 JPEG 파일이 아님 | 400 | "Invalid image file" |
| 유효하지 않은 API 키 | 401 | "Invalid API key" |
| 필드 누락 또는 알 수 없는 enum 값 | 422 | Validation error |
비동기 작업 동작
이 엔드포인트는 비동기 작업을 생성합니다. 요청 즉시 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/generate/effect/v1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "description=apply a glowing fantasy aura" \
-F "resolution=1K" \
-F "background_color=white"
cURL (이미지 포함):
curl -X POST "https://api.aetherforgeai.com/public/v1/generate/effect/v1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "description=apply a neon cyberpunk effect" \
-F "resolution=2K" \
-F "background_color=chroma_green" \
-F "image=@/path/to/input.png"