VberAI 개발자 API

VberAI 는 AI 슈퍼 누끼 등 기능을 앱, 게임, 자동화 파이프라인에 통합할 수 있는 RESTful HTTP API 를 제공합니다. API 키 + 서명 인증, 통일된 오류 코드, 크레딧 종량 과금.

API v1
안정 버전

API 문서

이미지 생성, 배경 제거, VberAI의 AI 파이프라인 실행을 개인 또는 엔터프라이즈 API 키로 HTTP를 통해 직접 수행합니다.

AI 레이어 분할

평면 UI 이미지를 넣으면 편집 가능한 레이어가 나옵니다. 배경 PNG, 요소마다 투명 PNG, 그리고 각 레이어의 이름·종류·위치·크기·쌓임 순서를 담은 JSON 목록입니다.

정적 이미지 한 장을 편집 가능한 멀티 레이어 장면 요소로 분해하며, 텍스트도 편집 가능한 상태로 유지합니다. UI 장면 자동 분해와 디자인 복원에 적합합니다.

동작 방식

  1. 1평면 이미지를 제출하면 taskId가 즉시 반환됩니다. 작업은 비동기로 실행되며 보통 2~3분 걸립니다.
  2. 2작업을 폴링하거나, 완료 시 webhook 호출을 받습니다.
  3. 3서명된 URL로 PNG를 내려받고 result.text에서 레이어 목록을 읽습니다.

엔드포인트

동작개인 키엔터프라이즈 키
제출POST /ai/tasksPOST /ai/org-services/ai-layer-split/execute-async
태스크 상태 폴링GET /ai/tasks/{taskId}GET /ai/org-services/tasks/{taskId}
새 다운로드 URL 재서명GET /ai/tasks/{taskId}/outputsGET /ai/org-services/tasks/{taskId}/outputs

엔터프라이즈 키는 /ai/org-services 라우트를 폴링해야 합니다

엔터프라이즈 키(vber_org_sk_)를 개인용 /ai/tasks 라우트로 보내면 401 INVALID_API_KEY가 반환됩니다——개인용 라우트는 개인 키만 받습니다. 엔터프라이즈 작업은 항상 /ai/org-services/tasks/{taskId}에서 폴링하십시오. cancel과 batch-status는 개인 키 전용입니다.

요청 봉투

서비스 파라미터는 두 키 유형에서 완전히 동일하며, 감싸는 형태만 다릅니다.

필드개인 키엔터프라이즈 키
아래에 나열된 서비스 파라미터.serviceCode + inputsinput
webhookUrl선택선택
webhookSecret선택선택

개인 키

두 키 모두 폴링만으로 사용할 수 있습니다. webhookUrl을 생략하면 직접 상태를 확인하고, 지정하면 완료 시 호출을 받습니다. 지정할 때는 공개 https URL이어야 합니다.

서비스 파라미터

매개변수타입필수설명
messagesarray둘 중 하나원본 이미지를 담는 대화 배열입니다. content[]에 { "type": "image_url", "image_url": { "url": "…" } } 파트를 하나 포함하세요. URL은 공개 https 링크 또는 인라인 data: URI일 수 있습니다.
referenceImagestring둘 중 하나원본 이미지의 간단한 지정 방식입니다. 공개 https URL 또는 인라인 data: URI를 넣으며, messages[] 대신 사용합니다.
referenceWidthnumber아니요원본의 선언 너비(픽셀). 제출 시 요금 등급을 정하는 데만 쓰이며 실제 크기는 이미지에서 측정합니다.
referenceHeightnumber아니요원본의 선언 높이(픽셀). 용도는 referenceWidth와 같습니다.
imageConfigobject아니요향후 생성 옵션을 위한 예약 필드로 현재는 무시됩니다.
원본 이미지는 messages[](OpenAI 형식 콘텐츠 파트) 또는 referenceImage 중 하나로 전달합니다. 둘 중 하나는 반드시 필요합니다.

인라인 base64 이미지

이미지를 직접 호스팅하지 않고 data: URI로 요청에 바로 넣을 수 있습니다. 플랫폼이 서버 측에 저장한 뒤 만들어진 URL을 파이프라인에 전달하므로 나머지 흐름은 그대로입니다.

json
{
  "referenceImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "referenceWidth": 1295,
  "referenceHeight": 726
}
인라인 미디어는 항목당 20 MB까지입니다(base64 문자열이 아니라 디코딩된 크기 기준). 그보다 큰 원본은 https URL로 전달하세요.
POST/ai/tasks
bash
curl -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

json
{
  "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.

queuedprocessingcompletedfailedcancelledtimeout

작업 필드

필드설명
taskId작업 식별자. 폴링, 산출물 조회, webhook 대조에 사용합니다.
serviceCode항상 ai-layer-split입니다.
statusqueued · processing · completed · failed · cancelled · timeout.
progress백엔드가 보고할 때의 대략적인 진행률이며 없으면 null입니다.
provider실행 채널이며 항상 external로 보고됩니다.
hasResultresult가 준비되면 true가 됩니다.
error실패 사유이며 정상일 때는 null입니다.
createdAt · startedAt · completedAt생성, 실행 시작, 완료 시각(ISO 8601, UTC).
expiresAt작업 기록과 파일이 삭제되는 시점으로 완료 후 7일입니다.
creditsEstimated · creditsActual제출 시 예약한 크레딧과 완료 시 실제로 차감된 크레딧입니다. 성공하면 동일하고 실패하면 전액 환불됩니다.
outputCount반환된 산출물 개수.
result아래에 설명한 결과 객체이며 작업 완료 후 나타납니다.

결과 가져오기

outputs 엔드포인트는 같은 result를 새로 서명한 다운로드 URL과 함께 반환합니다. URL이 만료되면 다시 호출하세요.

json
{
  "success": true,
  "data": {
    "taskId": "6a9db1431ef5f254006213e0",
    "status": "completed",
    "result": { "type": "images", "assets": [ … ], "text": "{ … }" },
    "completedAt": "2026-09-06T18:32:26.326Z"
  }
}

Webhook

webhookUrl을 지정하면 폴링과 동일한 내용을 POST로 보내 줍니다. webhookSecret을 함께 지정하면 검증용 서명 헤더가 붙습니다.

webhookSecret을 설정하면 각 전송에 X-Webhook-Signature 헤더가 포함됩니다——원본 JSON 페이로드의 HMAC-SHA256을 16진수로 인코딩한 값입니다. 여러분의 secret으로 다시 계산해 비교한 뒤에 페이로드를 신뢰하십시오. 전송에는 X-Idempotency-Key(taskId + status)도 함께 오므로 중복을 무시할 수 있습니다.

Webhook 페이로드

json
{
  "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 · 실패 시

json
{
  "taskId": "6a9db1431ef5f254006213e0",
  "serviceCode": "ai-layer-split",
  "status": "failed",
  "timestamp": "2026-09-06T18:32:26.401Z",
  "error": { "code": "EXECUTION_ERROR", "message": "Task processing failed" }
}

작업 상태 조회

GET/ai/tasks/{taskId}
bash
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"

산출물 가져오기

GET/ai/tasks/{taskId}/outputs
bash
curl https://api.vberai.com/api/ai/tasks/{taskId}/outputs \
  -H "X-API-Key: vber_sk_YOUR_KEY"

결과 객체

result는 두 부분입니다. assets[]의 레이어 이미지와 text에 JSON 문자열로 담긴 레이어 목록이며, assets[].name은 해당 레이어의 id와 일대일로 맞물립니다.

산출물

필드타입설명
indexnumberassets 배열에서의 위치.
namestring레이어 id로, 레이어 트리의 해당 노드 id와 같습니다. 이미지와 배치 정보를 짝지어 주는 값입니다.
urlstring서명된 다운로드 링크입니다. 쿼리 문자열을 지우지 말고 그대로 사용하세요.
mimeType"image/png"항상 알파 채널이 있는 image/png입니다.
sizenumber파일 크기(바이트).
sha256string파일의 SHA-256으로 무결성 확인과 중복 제거에 쓸 수 있습니다.
s3Keystring내부 오브젝트 키이며 참고용입니다.
다운로드 URL은 약 1시간 동안만 유효합니다. 만료되면 outputs를 다시 호출해 새 URL을 받으세요. 파일 자체는 7일간 보관됩니다.

레이어 이름 규칙

id는 서버가 부여하며 같은 작업 안에서는 변하지 않습니다. 접두사가 레이어의 성격을 나타냅니다.

값의미
Lbg배경 PNG: 감지된 모든 요소를 지우고 빈 자리를 다시 그린 전체 이미지입니다. 작업당 한 장이며 가장 아래 레이어입니다. imageSize보다 크게 올 수 있으니 배치할 크기에 맞춰 조정하세요.
A001, A002, …이미지 요소마다 PNG 한 장이며 목록 순서대로 번호가 붙습니다. 배경은 투명하고, 다른 요소에 가려졌던 부분은 채워져 있습니다. 픽셀 크기는 box × imageSize입니다.
T001, T002, …텍스트 요소. 의도적으로 이미지가 없습니다. 대신 정확한 문자열과 서식을 주므로 실제 텍스트로 다시 만들 수 있습니다.
group그룹 항목. 이미지가 없으며 어떤 레이어들이 한 묶음인지만 알려 줍니다.

완료된 작업

json
{
  "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)

result.text는 JSON 문자열이므로 먼저 파싱하세요. 각 레이어의 이름, 종류, 위치, 크기, 묶음, 쌓임 순서가 들어 있습니다.

최상위

필드타입설명
imageSize{ width, height }분석한 이미지의 픽셀 크기. 모든 box는 이 값에 대한 비율이며, 이 값(또는 원하는 크기)을 곱하면 픽셀이 됩니다.
nodesLayerNode[]모든 레이어가 담긴 평면 배열. 묶음은 parentId로, 쌓임 순서는 paintOrder로 표현되며 배열 순서 자체는 의미가 없습니다.

레이어 항목

필드타입설명
idstring레이어 id이며 대응하는 assets[].name과 같습니다(Lbg, A001, T001 …). 레이어와 PNG를 짝지을 때 사용합니다.
namestringAI가 추론한 읽기 쉬운 이름입니다(예: join_room_card). 설명적이지만 고유하지는 않으니 키는 id로, 표시는 name으로 쓰세요.
kindstring레이어 종류이며 아래 표를 참고하세요.
box[x, y, w, h]위치와 크기를 [x, y, 너비, 높이]로 나타내며 imageSize에 대한 비율입니다. 원점은 좌측 상단이고 imageSize를 곱하면 픽셀입니다.
parentIdstring | null속한 그룹의 id이며 루트 수준에서는 null입니다.
paintOrdernumber같은 부모를 가진 레이어 간 쌓임 순서로, 오름차순이 뒤에서 앞입니다. 배경은 -1입니다.
occludedboolean다른 요소에 가려진 부분이 있어 복원한 경우 true입니다.
instances[x, y, w, h][]같은 요소가 반복되는 추가 위치입니다. 이미지를 더 요청하지 말고 같은 PNG를 이 박스들에 배치하세요.
textobject텍스트 서식이며 kind가 text일 때만 나타납니다.

레이어 종류

값의미
background복원된 배경으로 한 장뿐이며 가장 먼저 그립니다.
group중첩을 위한 컨테이너이며 자체 이미지는 없습니다.
ui패널, 카드, 버튼 등 인터페이스 면이며 PNG가 제공됩니다.
icon작은 아이콘이며 PNG가 제공되고 처리 방식은 ui와 같습니다.
text프로그램 텍스트로 PNG가 없으며 편집 가능한 텍스트로 다시 만듭니다.

텍스트 속성

필드타입설명
textstring이미지에서 읽어 낸 문자열이며 원래 언어 그대로입니다.
fontSizePctnumber글자 높이를 imageSize.height에 대한 비율로 나타냅니다. 사용하는 높이를 곱하면 픽셀 글자 크기가 됩니다.
color"#RRGGBB"글자 채우기 색.
fontWeight100–900숫자 글꼴 두께.
italicboolean기울임 여부.
align"LEFT" | "CENTER" | "RIGHT"박스 안에서의 가로 정렬.
fontFamilystring권장 글꼴 패밀리이며 사용할 수 없으면 자체 기본 글꼴로 대체하세요.
strokeColor"#RRGGBB"글자 외곽선 색(외곽선이 있는 경우).
strokeWidthPctnumber외곽선 두께를 imageSize.height에 대한 비율로 나타낸 값.
shadow{ color, dxPct, dyPct, blurPct }그림자: 색상과, imageSize 너비·높이에 대한 비율로 표현한 오프셋 및 흐림.

레이어 목록(발췌)

json
{
  "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 …
  ]
}

구조

javascript
// 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 }
      }
    }
  ]
}

레이어 사용하기

위치와 크기가 비율이므로 같은 목록을 어떤 픽셀 크기에서도 그대로 쓸 수 있습니다.

  1. 1사용할 픽셀 크기를 정합니다. imageSize는 분석 당시 크기이고 모든 box는 그 비율입니다.
  2. 2Lbg를 맨 아래에 두어 전체 영역을 덮습니다.
  3. 3나머지를 정렬합니다. parentId로 묶고 그 안에서 paintOrder 오름차순(뒤에서 앞)으로 정렬합니다.
  4. 4ui와 icon의 PNG를 각자의 box에 배치하고 instances의 각 위치에도 같은 이미지를 놓습니다. 텍스트 레이어는 text의 문자열과 서식을 사용합니다.
Lbg는 imageSize보다 크게 올 수 있습니다. 같다고 가정하지 말고 크기를 맞추세요.
텍스트는 이미지가 아니라 문자열과 서식으로 오기 때문에 편집과 번역이 가능하고 어떤 크기에서도 선명합니다.

배치 목록 만들기

javascript
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 px120
2K≤ 2048 px180
4K> 2048 px250
등급 가격은 관리자가 조정할 수 있으므로 해당 호출의 정확한 금액은 제출 응답의 estimatedCredits를 기준으로 하세요.

제한

값설명
2048 px분석 전에 원본은 긴 변 2048 px로 축소됩니다.
300이미지 한 장당 최대 300개 요소까지 감지합니다.
20 MB인라인 base64 미디어는 항목당 20 MB까지입니다.
2~3분전체 처리 소요 시간(일반적인 경우).
7일작업 기록과 파일 보관 기간.
약 1시간서명된 다운로드 URL의 유효 기간.

오류

제출 단계의 오류는 동기적으로 반환되고, 실행 단계의 오류는 작업이 failed가 되며 error 객체가 함께 옵니다.

상태코드의미
400—요청 형식이 잘못되었습니다. 대부분 messages[]와 referenceImage 어디에도 원본 이미지가 없는 경우입니다.
401INVALID_API_KEY · INVALID_ORG_API_KEYAPI 키가 없거나 유효하지 않습니다.
402INSUFFICIENT_CREDITS · INSUFFICIENT_ORG_CREDITS이 이미지의 해상도 등급에 필요한 크레딧이 부족합니다.
403API_SERVICE_NOT_ALLOWED · ORG_DISABLED해당 키 또는 조직에 이 서비스를 호출할 권한이 없습니다.
413—인라인 base64 이미지가 20 MB 제한을 초과했습니다. https URL로 전달하세요.
429RATE_LIMIT_MINUTE · RATE_LIMIT_DAY · CONCURRENCY_LIMIT_EXCEEDED요청 빈도 또는 동시 실행 제한에 도달했습니다. 잠시 후 다시 시도하세요.
failederror.code작업 시작 후 실행이 실패했습니다. error.code와 error.message에 이유가 담기며 예약된 크레딧은 전액 환불됩니다.

오류 응답 — HTTP 400

json
{
  "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"
}

실패한 작업(폴링 응답)

json
{
  "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
  }
}