API
한줄 요약: API 메뉴를 열면 XBRUSH 공개 API 문서가 나옵니다. 작업실에서 쓰던 이미지·비디오 생성과 편집, 유틸리티 기능을 내 서비스에서 그대로 호출할 수 있습니다. 화면 오른쪽 위에는 내보내기 버튼이 두 개 있는데, LLM용 복사는 명세 전체를 AI 어시스턴트에게 넘겨 연동 코드를 대신 작성하게 하고, .txt 다운로드는 같은 문서를 파일로 저장합니다.
개요
API 문서 화면. 왼쪽에 엔드포인트 목록이, 오른쪽에 명세 본문이 있습니다.
상단 내비게이션에서 API를 클릭하면 열립니다. 문서를 읽는 데는 로그인이 필요하지 않습니다.
왼쪽 목차는 문서 전체를 순서대로 따라갑니다.
| 항목 | 내용 |
|---|---|
| 시작하기 | 비동기 흐름, Base URL, 과금, 레이트 리밋, 세션 |
| 인증 | X-API-Key 헤더와 키 발급 위치 |
| 엔드포인트 | 리소스별로 묶인 전체 엔드포인트와 요청 예시 |
| 모델과 파라미터 | 호출할 수 있는 모델과 각 모델이 받는 값 |
| 에러 코드 | 실패 응답의 의미 |
엔드포인트 아래 리소스 그룹은 다음과 같습니다.
| 그룹 | 엔드포인트 |
|---|---|
| Images | POST /images/generate · /images/edit · /images/upscale · /images/background-remover |
| Videos | POST /videos/generate · /videos/upscale |
| Requests | GET /requests/{requestId} · POST /requests/{requestId}/move · DELETE /requests/{requestId} |
| Sessions | POST /sessions · GET /sessions · GET /sessions/{sessionId} |
| Folders | GET /folders · POST /folders · PATCH /folders/{folderId} · DELETE /folders/{folderId} |
| Outputs | POST /outputs/{outputId}/move · DELETE /outputs/{outputId} |
| Models | GET /models |
| Balance | GET /balance |
LLM용 복사
오른쪽 위의 LLM용 복사 버튼을 누르면 API 문서 전체가 AI 어시스턴트가 읽기 좋은 평문 형태로 클립보드에 복사됩니다.
이 내용을 ChatGPT, Claude, Cursor 같은 코딩 어시스턴트에 붙여 넣으면 모델이 엔드포인트·파라미터·요청 흐름·제약 조건을 모두 파악한 상태가 됩니다. API를 일일이 설명할 필요 없이 곧바로 연동 코드를 작성하게 할 수 있습니다.
복사되는 텍스트는 이렇게 시작합니다.
# XBRUSH Public API
Generate and edit images and videos via API using XBRUSH workspace models.
Billing uses team points; results also appear in the team workspace.
Base URL: https://api-dev.xbrush.ai/v1
## Overview
- All generation requests are asynchronous: submit returns 202 with a
requestId; poll GET /requests/{requestId} until status is "completed",
then use the URLs in outputs.
- Points are charged upfront on submission and automatically refunded for
failed outputs (proportionally; fully on total failure).
- Rate limit: 60 requests per minute per API key, applied to generation
submissions (POST /images/* and /videos/*) only. Exceeding returns 429
with a Retry-After header. Reads (GET) are not limited.
- Idempotency: send an Idempotency-Key header (max 128 chars) for retry
safety. ...
- Sessions: every generation request REQUIRES sessionId — results live in
sessions ("results only exist in sessions"). ...
## Authentication
Protected endpoints require the X-API-Key header:
X-API-Key: sg_live_...
## Endpoints
### Images
#### POST /images/generate
...
이 형식이 LLM 입력으로 잘 동작하는 이유는 세 가지입니다.
- 해석할 마크업이 없는 평문 — 제목, 목록, 코드 블록만 사용합니다.
- 엔드포인트보다 규칙이 먼저 — 비동기 흐름, 과금, 레이트 리밋, 멱등성, 세션 필수 조건이 모두
## Overview에 먼저 나옵니다. 모델이 URL을 보기 전에 제약부터 읽게 됩니다. - 엔드포인트마다 실행 가능한 예시 — 각 엔드포인트에 완성된
curl명령이 붙어 있어, 모델이 형태를 지어내지 않고 동작하는 예시를 그대로 가져다 씁니다.
curl -X POST https://api-dev.xbrush.ai/v1/images/generate \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "z-image-free",
"prompt": "a cat astronaut floating in space",
"imageCount": 2,
"sessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}'
⚠️ 위 예시는 개발 환경 기준입니다. Base URL은 문서에서 복사한 값이 아니라 화면에 표시된 값을 사용하세요.
.txt 다운로드
.txt 다운로드는 같은 문서를 클립보드가 아니라 텍스트 파일로 저장합니다. 한 번 붙여넣고 마는 것이 아니라 어딘가에 남겨 둬야 할 때 씁니다.
- 저장소에 커밋해 연동 코드와 그 코드가 참조한 명세를 함께 관리합니다.
- AI 어시스턴트의 프로젝트나 지식 베이스에 첨부해 두면 대화를 새로 시작해도 계속 참조됩니다.
- 오프라인에서 참고하거나, XBRUSH 계정이 없는 동료에게 전달할 수 있습니다.
명세는 API가 발전하면서 바뀌므로, 연동 작업을 다시 시작할 때는 예전 파일을 믿지 말고 새로 내려받으세요.
문서에서 먼저 확인할 것
명세 전체를 읽지 않아도 이 API가 내 상황에 맞는지 판단할 수 있습니다. 설계를 좌우하는 부분만 정리하면 다음과 같습니다.
요청은 비동기입니다
이미지를 바로 돌려주는 엔드포인트는 없습니다. 생성 요청은 202와 requestId로 접수되고, GET /requests/{requestId}를 status가 completed가 될 때까지 폴링한 뒤 outputs의 URL을 읽습니다. 폴링 루프를 먼저 만들어야 나머지가 붙습니다.
세션은 필수입니다
모든 생성 요청에 sessionId가 필요합니다. 결과물은 세션 안에만 존재하며, 이 세션이 웹 작업실에서는 작업으로 보입니다.
POST /sessions로 세션을 만들고(folderId 생략 시 작업실 홈, name 생략 시 이름 없음) 반환된 sessionId를 전달하세요. 폴더 id를 넣거나, 없는 id를 넣거나, sessionId를 빠뜨리면 400 SESSION_REQUIRED로 거부되며 상세에 안내가 담깁니다. 세션 응답의 webUrl은 웹 작업실에서 그 세션을 바로 여는 딥링크입니다.
폴더는 세션을 담는 컨테이너입니다. 폴더 id는 POST /sessions나 GET /sessions 필터에 쓰는 값이지, 생성 요청에 넣는 값이 아닙니다.
과금과 환불
크레딧은 접수 시점에 선차감되고, 실패한 결과물에 대해서는 자동으로 환불됩니다. 일부만 실패하면 그만큼 비례해서, 전부 실패하면 전액 환불됩니다. 차감은 팀 크레딧에서 이뤄지고 생성된 결과물은 팀 작업실에도 함께 나타나므로, API 사용과 웹 사용이 하나의 잔액과 하나의 보관함을 공유합니다. 잔액은 GET /balance로 확인합니다.
레이트 리밋과 재시도
키당 분당 60건이며, 생성 접수(POST /images/*, /videos/*)에만 적용됩니다. 조회(GET)는 제한하지 않습니다. 초과하면 429와 Retry-After 헤더가 반환됩니다.
재시도를 안전하게 하려면 Idempotency-Key 헤더(최대 128자)를 보내세요. 같은 키에 같은 본문이면 최초의 202를 그대로 재생하고, 같은 키에 다른 본문이면 409를 반환합니다. 보존 기간은 24시간입니다. 재생된 202는 접수 시점의 상태(pending) 를 담고 있으므로, 실제 진행 상태는 폴링으로 확인해야 합니다.
인증과 키 관리
보호된 엔드포인트는 X-API-Key 헤더로 인증합니다.
X-API-Key: sg_live_...
키는 개인이 아니라 팀에 속하며, 팀의 소유자 또는 관리자가 팀 설정 → API에서 발급합니다.
🔑 키는 발급 시 단 한 번만 표시됩니다. 즉시 안전한 곳에 복사해 두세요. 잃어버리면 다시 확인할 수 없고 새로 발급받아야 합니다.
키가 팀 크레딧을 그대로 쓰기 때문에 비밀번호처럼 다뤄야 합니다. 서버 쪽에만 두고 클라이언트 코드나 공개 저장소에는 절대 넣지 마세요. 서비스별로 키를 따로 발급해 두면 하나를 폐기해도 나머지가 영향을 받지 않습니다.
- 자세히 보기: 팀 가이드 · 크레딧 사용 내역 · 워크스페이스 가이드