본문으로 건너뛰기

API

한줄 요약: API 메뉴를 열면 XBRUSH 공개 API 문서가 나옵니다. 작업실에서 쓰던 이미지·비디오 생성과 편집, 유틸리티 기능을 내 서비스에서 그대로 호출할 수 있습니다. 화면 오른쪽 위에는 내보내기 버튼이 두 개 있는데, LLM용 복사는 명세 전체를 AI 어시스턴트에게 넘겨 연동 코드를 대신 작성하게 하고, .txt 다운로드는 같은 문서를 파일로 저장합니다.


개요​

XBRUSH 공개 API 문서

API 문서 화면. 왼쪽에 엔드포인트 목록이, 오른쪽에 명세 본문이 있습니다. 본문은 시작하기와 Base URL https://api.xbrush.ai/v1로 시작하고, 오른쪽 위에 LLM용 복사와 .txt 다운로드 버튼이 있습니다.

상단 내비게이션에서 API를 클릭하면 열립니다. 문서를 읽는 데는 로그인이 필요하지 않습니다.

모든 요청은 운영 환경 Base URL로 보냅니다.

https://api.xbrush.ai/v1

왼쪽 목차는 문서 전체를 순서대로 따라갑니다.

항목내용
시작하기비동기 흐름, Base URL, 과금, 레이트 리밋, 세션
인증X-API-Key 헤더와 키 발급 위치
엔드포인트리소스별로 묶인 전체 엔드포인트와 요청 예시
모델과 파라미터호출할 수 있는 모델과 각 모델이 받는 값
에러 코드실패 응답의 의미

엔드포인트 아래 리소스 그룹은 다음과 같습니다.

그룹엔드포인트
ImagesPOST /images/generate · /images/edit · /images/upscale · /images/background-remover
VideosPOST /videos/generate · /videos/upscale
RequestsGET /requests/{requestId} · POST /requests/{requestId}/move · DELETE /requests/{requestId}
SessionsPOST /sessions · GET /sessions · GET /sessions/{sessionId}
FoldersGET /folders · POST /folders · PATCH /folders/{folderId} · DELETE /folders/{folderId}
OutputsPOST /outputs/{outputId}/move · DELETE /outputs/{outputId}
ModelsGET /models
BalanceGET /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.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.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"
}'

💡 예시의 sessionId는 자리표시용 값입니다. 먼저 POST /sessions로 세션을 만들고 반환된 sessionId를 넣으세요. 아래 세션은 필수입니다를 참고하세요.


.txt 다운로드​

.txt 다운로드는 같은 문서를 클립보드가 아니라 텍스트 파일로 저장합니다. 한 번 붙여넣고 마는 것이 아니라 어딘가에 남겨 둬야 할 때 씁니다.

  • 저장소에 커밋해 연동 코드와 그 코드가 참조한 명세를 함께 관리합니다.
  • AI 어시스턴트의 프로젝트나 지식 베이스에 첨부해 두면 대화를 새로 시작해도 계속 참조됩니다.
  • 오프라인에서 참고하거나, XBRUSH 계정이 없는 동료에게 전달할 수 있습니다.

명세는 API가 발전하면서 바뀌므로, 연동 작업을 다시 시작할 때는 예전 파일을 믿지 말고 새로 내려받으세요.


문서에서 먼저 확인할 것​

명세 전체를 읽지 않아도 이 API가 내 상황에 맞는지 판단할 수 있습니다. 설계를 좌우하는 부분만 정리하면 다음과 같습니다.

요청은 비동기입니다​

이미지를 바로 돌려주는 엔드포인트는 없습니다. 생성 요청은 202와 requestId로 접수되고, GET /requests/{requestId}를 status가 completed가 될 때까지 폴링한 뒤 outputs의 URL을 읽습니다. 폴링 루프를 먼저 만들어야 나머지가 붙습니다.

세션은 필수입니다​

모든 생성 요청에 sessionId가 필요합니다. 결과물은 세션 안에만 존재하며, 이 세션이 웹 작업실의 작업 세션입니다.

POST /sessions로 세션을 만들고(folderId 생략 시 작업실 홈, name 생략 시 웹에서 "New session"으로 표시) 반환된 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에서 발급합니다.

🔑 키는 발급 시 단 한 번만 표시됩니다. 즉시 안전한 곳에 복사해 두세요. 잃어버리면 다시 확인할 수 없고 새로 발급받아야 합니다.

키가 팀 크레딧을 그대로 쓰기 때문에 비밀번호처럼 다뤄야 합니다. 서버 쪽에만 두고 클라이언트 코드나 공개 저장소에는 절대 넣지 마세요. 서비스별로 키를 따로 발급해 두면 하나를 폐기해도 나머지가 영향을 받지 않습니다.