이미지 생성과 편집
적용 대상:
nexith-image· 비동기 작업 모델(제출 → 폴링/구독 → 산출물)
이미지는 동기 API가 아닙니다. 제출 요청은 세 가지만 수행합니다: 파라미터 검증, 속도 제한, 잔액 예약 및 작업 행 생성. 실제 생성은 worker가 비동기로 수행합니다. 전체 상태 머신:
提交 202 → queued → running → completed
↘ failed(重试耗尽)
↘ cancelled(客户端取消)1. 텍스트→이미지 생성#
curl -X POST https://api.nexith.ai/v1/images/generations \
-H "Authorization: Bearer $NEXITH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "nexith-image",
"prompt": "a cozy reading nook by the window, soft morning light",
"size": "1024x1024"
}'응답 202:
{"id": 123, "status": "pending", "idempotency_key": "…", "created_at": "2026-11-19T02:00:00Z"}파라미터:
| 필드 | 필수 | 설명 |
|---|---|---|
prompt |
예 | 프롬프트, 공백일 수 없습니다 |
model |
아니요 | 화이트리스트: nexith-image(기본값); 다른 값은 400 |
size |
아니요 | 현재 1024x1024 고정 |
idempotency_key |
아니요 | 멱등 키; 동일 사용자가 반복 제출하면 동일 작업을 반환하고 중복 차감하지 않습니다 |
2. 이미지 편집(img2img)#
이미지 편집은 두 단계입니다. 먼저 참조 이미지를 업로드해 안정적인 참조를 얻고, 그다음 편집 작업을 제출합니다.
2.1 참조 이미지 업로드#
curl -X POST https://api.nexith.ai/v1/files \
-H "Authorization: Bearer $NEXITH_JWT" \
-F "file=@./reference.png" \
-F "purpose=vision"{"id":"nx-file://<uuid>","object":"file","bytes":812345,"filename":"reference.png","mime_type":"image/png","purpose":"vision"}제한: ≤10 MB; image/png, image/jpeg, image/webp, image/gif만 허용(파일 시그니처로 검증).
2.2 편집 제출#
curl -X POST https://api.nexith.ai/v1/images/edits \
-H "Authorization: Bearer $NEXITH_JWT" \
-H "Content-Type: application/json" \
-d '{
"prompt": "把背景换成黄昏的海边",
"image": "nx-file://<uuid>",
"size": "1024x1024"
}'- JWT만 허용:
nx-API Key로 이 엔드포인트를 호출하면 403을 반환합니다(chat 사이트 전용). image는 현재 사용자 소유의nx-file://참조여야 하며, 존재하지 않거나 권한이 없으면 일괄 400입니다.- 편집은 생성과 동일한 SKU, 동일 가격, 동일 작업 흐름을 사용합니다.
3. 결과 가져오기#
폴링#
curl https://api.nexith.ai/v1/jobs/123 \
-H "Authorization: Bearer $NEXITH_API_KEY"{
"id": 123,
"public_model": "nexith-image",
"capability": "image.generate",
"status": "completed",
"attempt": 1,
"error_message": null,
"started_at": "2026-11-19T02:00:01Z",
"completed_at": "2026-11-19T02:00:45Z",
"created_at": "2026-11-19T02:00:00Z",
"artifacts": ["https://nexith-artifacts-prod.s3.us-west-2.amazonaws.com/images/…"]
}artifacts는 프리사인드 URL이며 유효 기간은 7일입니다. 만료 후에는 다시 생성하거나 직접 옮겨 두어야 합니다.error_message는 대외적으로 고정된 불투명 문구이며 업스트림 모델 이름/내부 오류를 포함하지 않습니다.
이벤트 구독(권장)#
curl -N https://api.nexith.ai/v1/jobs/123/events \
-H "Authorization: Bearer $NEXITH_API_KEY"프레임 형식은 스트리밍 프로토콜 · 작업 이벤트 스트림을 참고하세요. 클라이언트가 재연결하면 이벤트 0부터 재생되므로 이벤트를 놓치지 않습니다.
취소#
curl -X POST https://api.nexith.ai/v1/jobs/123/cancel \
-H "Authorization: Bearer $NEXITH_API_KEY"
# → {"id":123,"status":"cancelled"}취소 후 예약 금액을 전액 환불합니다.
4. 과금과 멱등#
| 항목 | 동작 |
|---|---|
| 예약 | 제출 시 $0.10/장으로 원자적 예약; 잔액 부족 시 402, 큐에 등록되지 않음 |
| 정산 | 완료 시 실제 금액으로 차감 |
| 환불 | 실패, 취소, 서버 오류 모두 자동 전액 환불 |
| 멱등 | (user_id, idempotency_key) 유니크; 반복 제출 시 원래 작업을 반환하고 중복 차감하지 않음 |
| 속도 제한 | 텍스트와 동일한 (Key, 모델) 속도 제한 체인, 초과 시 429이며 자금을 잠그지 않음 |
5. 프롬프트 권장 사항#
- 이미지 모델은 구체적인 명사 + 구도 + 조명 + 스타일에 더 민감하므로 추상적인 나열을 피하세요.
- 시리즈 일관성이 필요할 때는 확정된 이미지 한 장을 참조로 img2img 편집하는 것이 반복 생성보다 안정적입니다.
- 텍스트 렌더링은 여전히 오류가 날 수 있습니다. 정확한 텍스트가 필요하면 모델 생성에 맡기지 말고 후처리로 합성하는 것을 권장합니다.