VberAI 개발자 API
VberAI 는 AI 슈퍼 누끼 등 기능을 앱, 게임, 자동화 파이프라인에 통합할 수 있는 RESTful HTTP API 를 제공합니다. API 키 + 서명 인증, 통일된 오류 코드, 크레딧 종량 과금.
VberAI 는 AI 슈퍼 누끼 등 기능을 앱, 게임, 자동화 파이프라인에 통합할 수 있는 RESTful HTTP API 를 제공합니다. API 키 + 서명 인증, 통일된 오류 코드, 크레딧 종량 과금.
이미지 생성, 배경 제거, VberAI의 AI 파이프라인 실행을 개인 또는 엔터프라이즈 API 키로 HTTP를 통해 직접 수행합니다.
평면 UI 이미지를 넣으면 편집 가능한 레이어가 나옵니다. 배경 PNG, 요소마다 투명 PNG, 그리고 각 레이어의 이름·종류·위치·크기·쌓임 순서를 담은 JSON 목록입니다.정적 이미지 한 장을 편집 가능한 멀티 레이어 장면 요소로 분해하며, 텍스트도 편집 가능한 상태로 유지합니다. UI 장면 자동 분해와 디자인 복원에 적합합니다.
| 동작 | 개인 키 | 엔터프라이즈 키 |
|---|---|---|
| 제출 | POST /ai/tasks | POST /ai/org-services/ai-layer-split/execute-async |
| 태스크 상태 폴링 | GET /ai/tasks/{taskId} | GET /ai/org-services/tasks/{taskId} |
| 새 다운로드 URL 재서명 | GET /ai/tasks/{taskId}/outputs | GET /ai/org-services/tasks/{taskId}/outputs |
엔터프라이즈 키는 /ai/org-services 라우트를 폴링해야 합니다
서비스 파라미터는 두 키 유형에서 완전히 동일하며, 감싸는 형태만 다릅니다.
| 필드 | 개인 키 | 엔터프라이즈 키 |
|---|---|---|
| 아래에 나열된 서비스 파라미터. | serviceCode + inputs | input |
webhookUrl | 선택 | 선택 |
webhookSecret | 선택 | 선택 |
개인 키
| 매개변수 | 타입 | 필수 | 설명 |
|---|---|---|---|
messages | array | 둘 중 하나 | 원본 이미지를 담는 대화 배열입니다. content[]에 { "type": "image_url", "image_url": { "url": "…" } } 파트를 하나 포함하세요. URL은 공개 https 링크 또는 인라인 data: URI일 수 있습니다. |
referenceImage | string | 둘 중 하나 | 원본 이미지의 간단한 지정 방식입니다. 공개 https URL 또는 인라인 data: URI를 넣으며, messages[] 대신 사용합니다. |
referenceWidth | number | 아니요 | 원본의 선언 너비(픽셀). 제출 시 요금 등급을 정하는 데만 쓰이며 실제 크기는 이미지에서 측정합니다. |
referenceHeight | number | 아니요 | 원본의 선언 높이(픽셀). 용도는 referenceWidth와 같습니다. |
imageConfig | object | 아니요 | 향후 생성 옵션을 위한 예약 필드로 현재는 무시됩니다. |
이미지를 직접 호스팅하지 않고 data: URI로 요청에 바로 넣을 수 있습니다. 플랫폼이 서버 측에 저장한 뒤 만들어진 URL을 파이프라인에 전달하므로 나머지 흐름은 그대로입니다.
{
"referenceImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
"referenceWidth": 1295,
"referenceHeight": 726
}/ai/taskscurl -X POST https://api.vberai.com/api/ai/tasks \
-H "X-API-Key: vber_sk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"serviceCode": "ai-layer-split",
"inputs": {
"messages": [
{
"role": "user",
"content": [
{ "type": "image_url", "image_url": { "url": "https://example.com/lobby.png" } }
]
}
],
"referenceWidth": 1295,
"referenceHeight": 726
},
"webhookUrl": "https://your-server.com/hook",
"webhookSecret": "whsec_your_secret"
}'제출 응답 — HTTP 201
{
"success": true,
"message": "Created",
"data": {
"taskId": "6a9db1471ef5f25400621411",
"taskToken": "510932d23b39a0176837a3adfd6f64a773bc85f984417a7d6bcde08108494d30",
"status": "queued",
"estimatedCredits": 150,
"message": "Task queued for processing"
},
"timestamp": "2026-09-06T18:30:31.837Z"
}status가 completed 또는 failed가 될 때까지 폴링합니다. 작업 기록과 파일은 7일간 유지됩니다.
태스크는 이 값들을 거쳐 이동합니다. 종료 상태에 도달하면 폴링을 멈추십시오: completed, failed, cancelled 또는 timeout.
| 필드 | 설명 |
|---|---|
taskId | 작업 식별자. 폴링, 산출물 조회, webhook 대조에 사용합니다. |
serviceCode | 항상 ai-layer-split입니다. |
status | queued · processing · completed · failed · cancelled · timeout. |
progress | 백엔드가 보고할 때의 대략적인 진행률이며 없으면 null입니다. |
provider | 실행 채널이며 항상 external로 보고됩니다. |
hasResult | result가 준비되면 true가 됩니다. |
error | 실패 사유이며 정상일 때는 null입니다. |
createdAt · startedAt · completedAt | 생성, 실행 시작, 완료 시각(ISO 8601, UTC). |
expiresAt | 작업 기록과 파일이 삭제되는 시점으로 완료 후 7일입니다. |
creditsEstimated · creditsActual | 제출 시 예약한 크레딧과 완료 시 실제로 차감된 크레딧입니다. 성공하면 동일하고 실패하면 전액 환불됩니다. |
outputCount | 반환된 산출물 개수. |
result | 아래에 설명한 결과 객체이며 작업 완료 후 나타납니다. |
outputs 엔드포인트는 같은 result를 새로 서명한 다운로드 URL과 함께 반환합니다. URL이 만료되면 다시 호출하세요.
{
"success": true,
"data": {
"taskId": "6a9db1431ef5f254006213e0",
"status": "completed",
"result": { "type": "images", "assets": [ … ], "text": "{ … }" },
"completedAt": "2026-09-06T18:32:26.326Z"
}
}webhookUrl을 지정하면 폴링과 동일한 내용을 POST로 보내 줍니다. webhookSecret을 함께 지정하면 검증용 서명 헤더가 붙습니다.
webhookSecret을 설정하면 각 전송에 X-Webhook-Signature 헤더가 포함됩니다——원본 JSON 페이로드의 HMAC-SHA256을 16진수로 인코딩한 값입니다. 여러분의 secret으로 다시 계산해 비교한 뒤에 페이로드를 신뢰하십시오. 전송에는 X-Idempotency-Key(taskId + status)도 함께 오므로 중복을 무시할 수 있습니다.
Webhook 페이로드
{
"taskId": "6a9db1431ef5f254006213e0",
"serviceCode": "ai-layer-split",
"status": "completed",
"timestamp": "2026-09-06T18:32:26.401Z",
"result": {
"type": "images",
"assets": [ { "index": 0, "name": "Lbg", "url": "https://assets.vberai.org/…/0.png?<signed-query>", "mimeType": "image/png", "size": 5067542, "sha256": "7ceb4dad…" }, … ],
"text": "{\"imageSize\":{\"width\":1295,\"height\":726},\"nodes\":[…]}"
}
}Webhook · 실패 시
{
"taskId": "6a9db1431ef5f254006213e0",
"serviceCode": "ai-layer-split",
"status": "failed",
"timestamp": "2026-09-06T18:32:26.401Z",
"error": { "code": "EXECUTION_ERROR", "message": "Task processing failed" }
}작업 상태 조회
/ai/tasks/{taskId}curl https://api.vberai.com/api/ai/tasks/{taskId} \
-H "X-API-Key: vber_sk_YOUR_KEY"산출물 가져오기
/ai/tasks/{taskId}/outputscurl https://api.vberai.com/api/ai/tasks/{taskId}/outputs \
-H "X-API-Key: vber_sk_YOUR_KEY"result는 두 부분입니다. assets[]의 레이어 이미지와 text에 JSON 문자열로 담긴 레이어 목록이며, assets[].name은 해당 레이어의 id와 일대일로 맞물립니다.
| 필드 | 타입 | 설명 |
|---|---|---|
index | number | assets 배열에서의 위치. |
name | string | 레이어 id로, 레이어 트리의 해당 노드 id와 같습니다. 이미지와 배치 정보를 짝지어 주는 값입니다. |
url | string | 서명된 다운로드 링크입니다. 쿼리 문자열을 지우지 말고 그대로 사용하세요. |
mimeType | "image/png" | 항상 알파 채널이 있는 image/png입니다. |
size | number | 파일 크기(바이트). |
sha256 | string | 파일의 SHA-256으로 무결성 확인과 중복 제거에 쓸 수 있습니다. |
s3Key | string | 내부 오브젝트 키이며 참고용입니다. |
id는 서버가 부여하며 같은 작업 안에서는 변하지 않습니다. 접두사가 레이어의 성격을 나타냅니다.
| 값 | 의미 |
|---|---|
Lbg | 배경 PNG: 감지된 모든 요소를 지우고 빈 자리를 다시 그린 전체 이미지입니다. 작업당 한 장이며 가장 아래 레이어입니다. imageSize보다 크게 올 수 있으니 배치할 크기에 맞춰 조정하세요. |
A001, A002, … | 이미지 요소마다 PNG 한 장이며 목록 순서대로 번호가 붙습니다. 배경은 투명하고, 다른 요소에 가려졌던 부분은 채워져 있습니다. 픽셀 크기는 box × imageSize입니다. |
T001, T002, … | 텍스트 요소. 의도적으로 이미지가 없습니다. 대신 정확한 문자열과 서식을 주므로 실제 텍스트로 다시 만들 수 있습니다. |
| group | 그룹 항목. 이미지가 없으며 어떤 레이어들이 한 묶음인지만 알려 줍니다. |
완료된 작업
{
"success": true,
"data": {
"taskId": "6a9db1431ef5f254006213e0",
"serviceCode": "ai-layer-split",
"status": "completed",
"progress": null,
"provider": "external",
"hasResult": true,
"error": null,
"createdAt": "2026-09-06T18:30:27.398Z",
"startedAt": "2026-09-06T18:30:29.012Z",
"completedAt": "2026-09-06T18:32:26.326Z",
"expiresAt": "2026-09-13T18:32:26.326Z",
"creditsEstimated": 150,
"creditsActual": 150,
"outputCount": 23,
"result": {
"type": "images",
"assets": [
{
"index": 0,
"url": "https://assets.vberai.org/tmp/user-assets/6a76f458…/task_6a9db143…_background/0.png?<signed-query>",
"mimeType": "image/png",
"s3Key": "tmp/user-assets/6a76f458…/task_6a9db143…_background/0.png",
"size": 5067542,
"sha256": "7ceb4dad585d2c60368e35c994ea53819b45f29f84fa5ec36704e9b3794a5f5e",
"name": "Lbg"
},
{
"index": 1,
"url": "https://assets.vberai.org/ai-deliveries/6a76f458…/task_6a9db143…/A001-ab405a4a….png?<signed-query>",
"mimeType": "image/png",
"s3Key": "ai-deliveries/6a76f458…/task_6a9db143…/A001-ab405a4a….png",
"size": 73117,
"sha256": "ab405a4a607a7c9e95bd5dba0150f84743c73362f482bbeb990fc4687c90055e",
"name": "A001"
},
… 21 more "A002" … "A022" assets …
],
"text": "{\"imageSize\":{\"width\":1295,\"height\":726},\"nodes\":[{\"id\":\"Lbg\",…},{\"id\":\"A001\",…},…]}"
}
}
}result.text는 JSON 문자열이므로 먼저 파싱하세요. 각 레이어의 이름, 종류, 위치, 크기, 묶음, 쌓임 순서가 들어 있습니다.
| 필드 | 타입 | 설명 |
|---|---|---|
imageSize | { width, height } | 분석한 이미지의 픽셀 크기. 모든 box는 이 값에 대한 비율이며, 이 값(또는 원하는 크기)을 곱하면 픽셀이 됩니다. |
nodes | LayerNode[] | 모든 레이어가 담긴 평면 배열. 묶음은 parentId로, 쌓임 순서는 paintOrder로 표현되며 배열 순서 자체는 의미가 없습니다. |
| 필드 | 타입 | 설명 |
|---|---|---|
id | string | 레이어 id이며 대응하는 assets[].name과 같습니다(Lbg, A001, T001 …). 레이어와 PNG를 짝지을 때 사용합니다. |
name | string | AI가 추론한 읽기 쉬운 이름입니다(예: join_room_card). 설명적이지만 고유하지는 않으니 키는 id로, 표시는 name으로 쓰세요. |
kind | string | 레이어 종류이며 아래 표를 참고하세요. |
box | [x, y, w, h] | 위치와 크기를 [x, y, 너비, 높이]로 나타내며 imageSize에 대한 비율입니다. 원점은 좌측 상단이고 imageSize를 곱하면 픽셀입니다. |
parentId | string | null | 속한 그룹의 id이며 루트 수준에서는 null입니다. |
paintOrder | number | 같은 부모를 가진 레이어 간 쌓임 순서로, 오름차순이 뒤에서 앞입니다. 배경은 -1입니다. |
occluded | boolean | 다른 요소에 가려진 부분이 있어 복원한 경우 true입니다. |
instances | [x, y, w, h][] | 같은 요소가 반복되는 추가 위치입니다. 이미지를 더 요청하지 말고 같은 PNG를 이 박스들에 배치하세요. |
text | object | 텍스트 서식이며 kind가 text일 때만 나타납니다. |
| 값 | 의미 |
|---|---|
background | 복원된 배경으로 한 장뿐이며 가장 먼저 그립니다. |
group | 중첩을 위한 컨테이너이며 자체 이미지는 없습니다. |
ui | 패널, 카드, 버튼 등 인터페이스 면이며 PNG가 제공됩니다. |
icon | 작은 아이콘이며 PNG가 제공되고 처리 방식은 ui와 같습니다. |
text | 프로그램 텍스트로 PNG가 없으며 편집 가능한 텍스트로 다시 만듭니다. |
| 필드 | 타입 | 설명 |
|---|---|---|
text | string | 이미지에서 읽어 낸 문자열이며 원래 언어 그대로입니다. |
fontSizePct | number | 글자 높이를 imageSize.height에 대한 비율로 나타냅니다. 사용하는 높이를 곱하면 픽셀 글자 크기가 됩니다. |
color | "#RRGGBB" | 글자 채우기 색. |
fontWeight | 100–900 | 숫자 글꼴 두께. |
italic | boolean | 기울임 여부. |
align | "LEFT" | "CENTER" | "RIGHT" | 박스 안에서의 가로 정렬. |
fontFamily | string | 권장 글꼴 패밀리이며 사용할 수 없으면 자체 기본 글꼴로 대체하세요. |
strokeColor | "#RRGGBB" | 글자 외곽선 색(외곽선이 있는 경우). |
strokeWidthPct | number | 외곽선 두께를 imageSize.height에 대한 비율로 나타낸 값. |
shadow | { color, dxPct, dyPct, blurPct } | 그림자: 색상과, imageSize 너비·높이에 대한 비율로 표현한 오프셋 및 흐림. |
레이어 목록(발췌)
{
"imageSize": { "width": 1295, "height": 726 },
"nodes": [
{ "id": "Lbg", "name": "background", "kind": "background", "box": [0, 0, 1, 1], "parentId": null, "paintOrder": -1, "occluded": false },
{ "id": "A001", "name": "player_info_bg", "kind": "ui", "box": [0.0026, 0, 0.2644, 0.1322], "parentId": null, "paintOrder": 1, "occluded": false },
{ "id": "A005", "name": "player_avatar", "kind": "ui", "box": [0.0108, 0.0069, 0.068, 0.1157], "parentId": null, "paintOrder": 5, "occluded": false },
{ "id": "A013", "name": "join_room_card", "kind": "ui", "box": [0.3153, 0.2546, 0.1825, 0.6906], "parentId": null, "paintOrder": 13, "occluded": false },
{
"id": "T001", "name": "player_name", "kind": "text",
"box": [0.0827, 0.0193, 0.1543, 0.0427], "parentId": null, "paintOrder": 18, "occluded": false,
"text": { "text": "明月清风晓星尘", "fontSizePct": 0.022, "color": "#FFFFFF", "fontWeight": 400, "align": "LEFT" }
},
{
"id": "T003", "name": "currency_1_amount", "kind": "text",
"box": [0.3614, 0.0372, 0.0533, 0.0455], "parentId": null, "paintOrder": 20, "occluded": false,
"text": {
"text": "87万", "fontSizePct": 0.0248, "color": "#FFFFFF", "fontWeight": 700, "align": "CENTER",
"strokeColor": "#5C3A21", "strokeWidthPct": 0.0028
}
},
… 23 more nodes …
]
}구조
// JSON.parse(result.text)
{
imageSize: { width, height }, // px of the analysed image
nodes: [
{
id: "Lbg" | "A001" | "T001" | "<group id>", // == asset name
name: "join_room_card", // AI-given, may repeat
kind: "background" | "group" | "ui" | "icon" | "text",
box: [x, y, w, h], // fractions 0..1 of imageSize
parentId: null | "<group id>",
paintOrder: -1 | 0 | 1 | ..., // ascending = bottom → top (siblings)
occluded: false,
instances: [[x, y, w, h]], // optional: repeated placements
text: { // only when kind === "text"
text, fontSizePct, color, fontWeight, italic, align,
fontFamily, strokeColor, strokeWidthPct,
shadow: { color, dxPct, dyPct, blurPct }
}
}
]
}위치와 크기가 비율이므로 같은 목록을 어떤 픽셀 크기에서도 그대로 쓸 수 있습니다.
배치 목록 만들기
const { result } = task; // from polling, outputs or the webhook
const tree = JSON.parse(result.text);
const { width: W, height: H } = tree.imageSize; // reference pixel size
const png = Object.fromEntries(result.assets.map((a) => [a.name, a.url]));
// 1) box fractions -> pixels, at whatever size you work at
const px = ([x, y, w, h]) => ({ x: x * W, y: y * H, width: w * W, height: h * H });
// 2) back -> front within each parent
const childrenOf = (parentId) =>
tree.nodes
.filter((n) => n.parentId === parentId)
.sort((a, b) => a.paintOrder - b.paintOrder);
// 3) flatten into a placement list your app can consume
function collect(parentId = null, out = []) {
for (const n of childrenOf(parentId)) {
if (n.kind === "group") { collect(n.id, out); continue; }
for (const box of [n.box, ...(n.instances ?? [])]) {
out.push({
id: n.id,
name: n.name, // e.g. "join_room_card"
kind: n.kind, // background | ui | icon | text
...px(box), // x, y, width, height in px
order: n.paintOrder,
image: n.kind === "text" ? null : png[n.id],
text: n.text ?? null, // content + styling, text only
});
}
}
return out;
}
const layers = collect(); // ready to place or import
호출당 정액이며 원본 이미지의 긴 변에 따른 등급으로 정해집니다. 제출 시 estimatedCredits로 반환되고 완료 시 차감되며, 실패한 작업은 전액 환불됩니다.
| 등급 | 긴 변 | 크레딧 |
|---|---|---|
1K | ≤ 1024 px | 120 |
2K | ≤ 2048 px | 180 |
4K | > 2048 px | 250 |
| 값 | 설명 |
|---|---|
2048 px | 분석 전에 원본은 긴 변 2048 px로 축소됩니다. |
300 | 이미지 한 장당 최대 300개 요소까지 감지합니다. |
20 MB | 인라인 base64 미디어는 항목당 20 MB까지입니다. |
| 2~3분 | 전체 처리 소요 시간(일반적인 경우). |
| 7일 | 작업 기록과 파일 보관 기간. |
| 약 1시간 | 서명된 다운로드 URL의 유효 기간. |
제출 단계의 오류는 동기적으로 반환되고, 실행 단계의 오류는 작업이 failed가 되며 error 객체가 함께 옵니다.
| 상태 | 코드 | 의미 |
|---|---|---|
| 400 | — | 요청 형식이 잘못되었습니다. 대부분 messages[]와 referenceImage 어디에도 원본 이미지가 없는 경우입니다. |
| 401 | INVALID_API_KEY · INVALID_ORG_API_KEY | API 키가 없거나 유효하지 않습니다. |
| 402 | INSUFFICIENT_CREDITS · INSUFFICIENT_ORG_CREDITS | 이 이미지의 해상도 등급에 필요한 크레딧이 부족합니다. |
| 403 | API_SERVICE_NOT_ALLOWED · ORG_DISABLED | 해당 키 또는 조직에 이 서비스를 호출할 권한이 없습니다. |
| 413 | — | 인라인 base64 이미지가 20 MB 제한을 초과했습니다. https URL로 전달하세요. |
| 429 | RATE_LIMIT_MINUTE · RATE_LIMIT_DAY · CONCURRENCY_LIMIT_EXCEEDED | 요청 빈도 또는 동시 실행 제한에 도달했습니다. 잠시 후 다시 시도하세요. |
| failed | error.code | 작업 시작 후 실행이 실패했습니다. error.code와 error.message에 이유가 담기며 예약된 크레딧은 전액 환불됩니다. |
오류 응답 — HTTP 400
{
"success": false,
"message": "A reference image is required: provide it as an `image_url` part inside messages[].content[], or pass `referenceImage` directly.",
"timestamp": "2026-09-06T18:30:27.398Z"
}실패한 작업(폴링 응답)
{
"success": true,
"data": {
"taskId": "6a9db1431ef5f254006213e0",
"serviceCode": "ai-layer-split",
"status": "failed",
"hasResult": false,
"error": { "code": "EXECUTION_ERROR", "message": "Task processing failed" },
"creditsEstimated": 150,
"creditsActual": 0,
"outputCount": 0
}
}