Stagify.ai › API 문서

Stagify API

API 대시보드

직접 작성한 코드로 부동산 사진을 가상 스테이징하세요. HTTP 호출 한 번에 스테이징된 이미지 한 장이 돌아옵니다. 선불 크레딧은 이미지당 0.15달러이며, 구독도 최소 사용량도 없고 통제를 벗어나는 청구서도 없습니다.

기본 URL: https://stagify.ai/api/v1
인증: Bearer stg_live_…
콘텐츠 유형: multipart/form-data

소개

이 API가 제공하는 것은 하나입니다. 웹 앱 뒤에 있는 스테이징 파이프라인입니다. 방 사진을 올리고 방 유형과 가구 스타일을 지정하면 같은 응답으로 스테이징된 이미지를 받습니다. 작업 큐도 없고 정상 경로에서 폴링할 것도 없습니다.

크레딧은 이미지 한 장 단위입니다. 미리 구매하고 렌더링이 성공할 때마다 하나씩 차감됩니다. 실패한 렌더링은 자동으로 환불되므로 실제로 받은 사진에 대해서만 지불합니다. 잔액이 선불이기 때문에 키를 도난당해도 손실은 남은 잔액까지입니다. 월말 청구서는 없습니다.

키는 서버 간 통신용입니다. API는 CORS 헤더를 보내지 않으므로 브라우저에서 직접 호출할 수 없습니다. 이는 의도된 설계이며, 브라우저 JavaScript에서 닿을 수 있는 키는 이미 유출된 키입니다. 키는 한 번만 표시하고 해시만 저장하며 폐기는 즉시 적용됩니다.

빠른 시작

API 키 페이지에서 키를 만들고 크레딧 팩을 구매한 뒤 사진을 보내세요. 응답에는 스테이징된 이미지가 data URL로 담깁니다.

curl https://stagify.ai/api/v1/renders \
  -H "Authorization: Bearer $STAGIFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "image=@living-room.jpg" \
  -F "roomType=Living room" \
  -F "furnitureStyle=modern" \
  -F "labelVirtuallyStaged=true"

렌더링에는 몇 분이 걸릴 수 있습니다. 클라이언트의 읽기 타임아웃을 300초로 설정하고 같은 Idempotency-Key로 재시도하세요. 사진 한 장에 두 번 청구되지 않도록 보장하는 것이 바로 이 부분입니다.

크레딧 팩

가격 불러오는 중…

요청 파라미터

POST /api/v1/renders를 multipart/form-data로 보냅니다. 아래의 모든 허용 값은 GET /api/v1/options에서도 JSON으로 제공되며 API 키가 필요 없습니다. 따라서 이 표를 코드에 박아 넣는 대신 클라이언트가 직접 드롭다운을 채울 수 있습니다.

필드	타입	설명
`image`	file	필수. 방 사진. JPEG, PNG 또는 WebP, 최대 25MB. 확장자가 아니라 MIME 타입을 확인합니다.
`roomType`	enum	`Bedroom`, `Living room`, `Dining room`, `Kitchen`, `Office`, `Bathroom`, `Outdoors`, `Dorm`. 기본값 `Living room`. 대소문자와 공백을 구분하며, 인식할 수 없는 값은 거부되지 않습니다. 자유 텍스트로 프롬프트에 그대로 들어가므로 `Living Room`은 `Living room`이 아닙니다.
`furnitureStyle`	enum	`standard`, `modern`, `midcentury`, `scandinavian`, `luxury`, `coastal`, `farmhouse`, `custom`. 기본값 `standard`이며, 인식할 수 없는 값도 조용히 이 값이 됩니다. `custom`은 내장 스타일 문구 대신 `additionalPrompt`를 사용합니다.
`additionalPrompt`	string	이번 렌더링에 대한 자유 텍스트 지시.
`removeFurniture`	boolean	스테이징 전에 방을 비웁니다. `true` 또는 `on`을 보내세요. `1`과 `yes`를 포함한 그 밖의 값은 모두 거짓으로 읽힙니다.
`keepFurniture`	string	남길 것을 자유 텍스트로 지정합니다. 예: `keep the dining table and the built-in shelves`. `removeFurniture`가 켜져 있을 때만 읽습니다. 500자.
`furnitureImage`	file[]	참고할 가구 사진 최대 5장. 형식과 크기 제한은 `image`와 같습니다.
`labelVirtuallyStaged`	boolean	결과 이미지에 “Virtually staged” 고지를 새깁니다.
`stampStyle`	enum	`dark`, `light`, `minimal`, `banner`. 기본값 `dark`. 대소문자를 구분하지 않으며, 인식할 수 없는 값은 기본값으로 돌아갑니다.
`stampScale`	number	`0.7`부터 `1.6`까지, 기본값 `1`. 범위를 벗어난 값은 거부되지 않고 경계값으로 잘립니다.
`stampLang`	enum	고지 문구의 언어: `english`, `spanish`, `french`, `german`, `chinese`, `korean`, `portuguese`, `russian`, `italian`, `japanese`, `dutch`. 기본값 `english`.
`variations`	integer	`1`만 허용됩니다. 더 필요하면 동시에 요청을 보내세요.

멱등성

렌더링은 몇 분 동안 연결을 붙잡고 있습니다. 그래서 실제로 문제가 되는 장애는 작업이 끝난 뒤 소켓이 끊기는 경우입니다. 요금은 청구되었는데 손에 쥔 것은 없습니다. 모든 요청에 Idempotency-Key 헤더를 보내고 같은 값으로 재시도하세요.

저장된 기록	재시도 시 동작
성공한 요청, 같은 파라미터	저장된 결과를 `X-Stagify-Replayed: true`와 함께 반환합니다. 두 번째 청구는 없습니다.
아직 실행 중인 요청	`409 REQUEST_IN_FLIGHT`. 기다렸다가 다시 시도하세요.
렌더링 도중 중단된 요청	기존 청구 그대로 다시 실행합니다. 최대 세 번까지.
같은 키에 다른 파라미터	`422 IDEMPOTENCY_KEY_REUSED`. 새 키를 사용하세요.

헤더를 생략해도 되며, 그 경우 재전송 보호가 없습니다. 이것이 정직한 기본 동작입니다. 사진에서 키를 유도하지는 않습니다. 같은 방을 정말로 따로 렌더링한 두 요청이 충돌해 두 번째 호출자가 첫 번째의 이미지를 받게 되기 때문입니다.

가상 스테이징 고지

많은 MLS 및 NAR 규정은 가상 스테이징한 사진에 그 사실을 표시하도록 요구합니다. labelVirtuallyStaged는 그 고지를 픽셀에 새깁니다. 후속 도구가 제거할 수 있는 메타데이터로 붙이지 않습니다.

고지를 넣을 수 없으면 이미지는 표시 없이 전달되는 대신 보류되고, 호출은 500 DISCLOSURE_STAMP_FAILED로 응답하며 크레딧은 환불됩니다. 이 동작은 끌 수 없으며, 키별 기본값으로 조용히 비활성화할 수도 없습니다.

오류

모든 실패는 { "error": "…", "code": "…" }로 응답합니다. 메시지가 아니라 code로 분기하세요. 메시지는 바뀌지만 코드는 바뀌지 않습니다.

상태	코드	조치
401	`API_KEY_MISSING` / `API_KEY_INVALID` / `API_KEY_REVOKED`	`Authorization` 헤더를 확인하거나 새 키를 발급하세요.
402	`INSUFFICIENT_CREDITS`	충전하세요. 본문에 `credits_remaining`이 있습니다.
403	`ACCOUNT_SUSPENDED`	지원팀에 문의하세요.
400	`VARIATIONS_UNSUPPORTED`	이 API는 요청당 이미지 한 장을 렌더링합니다. 대신 동시 요청을 보내세요.
409	`REQUEST_IN_FLIGHT`	해당 멱등 키가 아직 실행 중입니다. 기다렸다가 다시 시도하세요.
409	`CONCURRENCY_LIMIT`	동시 렌더링이 너무 많습니다. 몇 초 후 다시 시도하세요.
422	`IDEMPOTENCY_KEY_REUSED`	같은 키를 다른 파라미터로 재사용했습니다. 새 키를 사용하세요.
422	`NO_IMAGE_GENERATED`	모델이 아무것도 반환하지 않았습니다. 환불되었습니다. 다시 시도하거나 다른 사진을 사용하세요.
429	`RATE_LIMITED`	속도를 줄이고 다시 시도하세요.
500	`DISCLOSURE_STAMP_FAILED`	고지를 넣을 수 없어 이미지를 보류했습니다. 환불되었습니다.
500	`RENDER_FAILED`	환불되었습니다. 지원팀에 문의할 때 `ref`를 알려주세요.

기타 엔드포인트

GET /api/v1/options: 위 모든 열거형의 허용 값. API 키가 필요 없습니다.
GET /api/v1/me: 내 키가 작동하는가? 계정과 잔액을 반환합니다.
GET /api/v1/credits: 잔액과 누적 합계.
GET /api/v1/renders/{id}: 렌더링 하나의 상태.

모든 응답에 X-Stagify-Credits-Remaining이 포함되므로 따로 조회하지 않아도 잔액이 줄어드는 것을 볼 수 있습니다.

문의, 한도 상향, 카드 대신 청구서 발행: team@stagify.ai.