NNexithDocs
상태대시보드 ↗
개요 및 빠른 시작모델 카탈로그가이드API 레퍼런스연동OAuth2 / OIDC

이미지 생성과 편집

적용 대상: 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 편집하는 것이 반복 생성보다 안정적입니다.
  • 텍스트 렌더링은 여전히 오류가 날 수 있습니다. 정확한 텍스트가 필요하면 모델 생성에 맡기지 말고 후처리로 합성하는 것을 권장합니다.