VberAI 개발자 API
VberAI 는 AI 슈퍼 누끼 등 기능을 앱, 게임, 자동화 파이프라인에 통합할 수 있는 RESTful HTTP API 를 제공합니다. API 키 + 서명 인증, 통일된 오류 코드, 크레딧 종량 과금.
VberAI 는 AI 슈퍼 누끼 등 기능을 앱, 게임, 자동화 파이프라인에 통합할 수 있는 RESTful HTTP API 를 제공합니다. API 키 + 서명 인증, 통일된 오류 코드, 크레딧 종량 과금.
이미지 생성, 배경 제거, VberAI의 AI 파이프라인 실행을 개인 또는 엔터프라이즈 API 키로 HTTP를 통해 직접 수행합니다.
VberAI API는 studio를 구동하는 것과 동일한 AI 파이프라인——배경 제거, 슈퍼 매팅, 이미지 생성 등——을 간단한 HTTP 엔드포인트로 제공합니다. API 키로 인증하고 작업을 제출한 뒤, 결과를 다시 읽거나 webhook으로 받습니다.
통일된 요청 형태
모든 서비스는 { input } 본문을 받고, 폴링하거나 webhook으로 받을 수 있는 태스크를 반환합니다.
두 가지 키 유형
개인 키는 개별 개발자용, 엔터프라이즈 키는 조직의 서버 간 사용을 위한 것입니다.
예측 가능한 과금
크레딧은 제출 시 예약되고 성공 시 정산됩니다. 실패한 작업은 자동으로 환불됩니다.
# 1. Submit a job
curl -X POST https://api.vberai.com/api/ai/services/ai-image-bg-remove/execute \
-H "X-API-Key: vber_sk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"imageUrl": "https://example.com/photo.png"}}'
# => { "data": { "taskId": "...", "status": "queued" } }
# 2. Poll until status is "completed"
curl https://api.vberai.com/api/ai/tasks/{taskId} \
-H "X-API-Key: vber_sk_YOUR_KEY"모든 요청은 X-API-Key 헤더로 전송되는 API 키로 인증됩니다. 키에는 두 종류가 있으며 각기 다른 라우트를 사용합니다——키 유형에 맞지 않는 라우트를 선택하는 것이 401의 가장 흔한 원인입니다.
개인 키 —— vber_sk_
개별 개발자용입니다. 계정의 API 키 페이지에서 셀프서비스로 생성합니다(API 액세스가 포함된 플랜 필요). 개인 크레딧에서 과금됩니다. /ai/services 및 /ai/tasks 라우트를 사용합니다.
엔터프라이즈 키 —— vber_org_sk_
조직의 서버 간 사용을 위한 것입니다. 조직 관리자가 엔터프라이즈 포털에서 발급하며, 조직이 승인받은 서비스로 제한됩니다. 조직의 크레딧 풀에서 과금됩니다. /ai/org-services 라우트를 사용합니다.
| 항목 | 개인 키 | 엔터프라이즈 키 |
|---|---|---|
| 키 접두사 | vber_sk_ | vber_org_sk_ |
| 라우트 접두사 | /ai/services, /ai/tasks | /ai/org-services |
| 발급 방법 | 셀프서비스, 계정 설정 | 조직 관리자, 엔터프라이즈 포털 |
| 과금 대상 | 개인 크레딧 | 조직 크레딧 |
| 제한 | 분당 / 일당 요청 제한 | 조직별 동시 실행 수(맞춤 설정) |
X-API-Key: vber_sk_... # personal key
X-API-Key: vber_org_sk_... # enterprise key베이스 URL
https://api.vberai.com/api모든 서비스는 해당 서비스의 매개변수를 담은 input 객체를 포함하는 JSON 본문을 받습니다. 결과를 받는 방식은 서비스의 실행 모드에 따라 달라집니다.
동기 서비스
빠른 서비스(예: 채팅이나 텍스트 번역)는 동일한 응답에서 HTTP 200과 함께 결과를 인라인으로 반환합니다. 폴링이 필요 없습니다.
비동기 서비스
무거운 서비스(이미지 생성, 매팅, 배경 제거)는 taskId와 함께 HTTP 202를 반환합니다. 완료되면 태스크를 폴링하거나 webhook으로 결과를 받습니다.
개인 키
엔터프라이즈 키
{
"input": {
"imageUrl": "https://example.com/photo.png"
},
"webhookUrl": "https://your-server.com/hook"
}HTTP 200 # sync: result inline
HTTP 202 # async: { "taskId": "...", "status": "queued" }비동기 작업은 taskId를 반환합니다. 상태가 종료 값이 될 때까지 태스크를 폴링한 뒤 결과를 읽습니다. 어떤 라우트를 폴링하는지는 키 유형에 따라 달라집니다——이것이 가장 중요하게 정확히 지켜야 할 부분입니다.
| 동작 | 개인 키 | 엔터프라이즈 키 |
|---|---|---|
| 태스크 상태 폴링 | GET /ai/tasks/{taskId} | GET /ai/org-services/tasks/{taskId} |
| 새 다운로드 URL 재서명 | 상태 응답에서 읽기 | GET /ai/org-services/tasks/{taskId}/outputs |
| 태스크 취소 | POST /ai/tasks/{taskId}/cancel | 제공되지 않음 |
| 배치 상태 | GET /ai/tasks/batch-status | 제공되지 않음 |
엔터프라이즈 키는 /ai/org-services 라우트를 폴링해야 합니다
태스크는 이 값들을 거쳐 이동합니다. 종료 상태에 도달하면 폴링을 멈추십시오: completed, failed, cancelled 또는 timeout.
status가 completed이면 result.assets가 출력 이미지를 담습니다. 각 asset에는 url(만료되는 사전 서명 다운로드 링크), mimeType, index가 있으며, width, height, size, expiresAt은 가능한 경우에 나타납니다. URL은 신속히 가져오십시오——엔터프라이즈 키는 /outputs 엔드포인트에서 새 링크를 다시 요청할 수 있습니다.
# personal
curl https://api.vberai.com/api/ai/tasks/{taskId} \
-H "X-API-Key: vber_sk_YOUR_KEY"
# enterprise
curl https://api.vberai.com/api/ai/org-services/tasks/{taskId} \
-H "X-API-Key: vber_org_sk_YOUR_ORG_KEY"완료된 태스크
{
"success": true,
"data": {
"taskId": "6a97e277a148c970dd545f40",
"serviceCode": "super-matting",
"status": "completed",
"creditsEstimated": 10,
"creditsActual": 10,
"outputCount": 1,
"result": {
"type": "images",
"assets": [
{
"index": 0,
"url": "https://assets.vberai.org/tmp/user-assets/.../0.png?signature=...",
"mimeType": "image/png",
"expiresAt": "2026-01-22T10:30:12.000Z"
}
]
},
"completedAt": "2026-01-15T10:30:12.000Z"
}
}멱등성을 사용하면 네트워크 오류 후 제출을 안전하게 재시도해도 중복 작업이 생기거나 이중으로 과금되지 않습니다.
엔터프라이즈 키
/execute-async에서 선택적으로 Idempotency-Key 헤더(직접 생성하는 값으로 최대 200자——UUID가 이상적)를 전송할 수 있습니다. 동일한 키로 재시도하면 새 태스크를 만들지 않고 원래 태스크를 반환합니다. 서버는 중복 제거만 하며, 키를 대신 생성해 주지는 않습니다.
개인 키
개인 API 키 요청은 현재 멱등 키를 지원하지 않습니다. 이전 요청이 태스크를 생성하지 않았음을 확인한 뒤(받은 taskId로 폴링) 재시도하십시오.
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000폴링 대신, 태스크가 종료 상태에 도달했을 때 VberAI가 결과를 여러분의 서버로 POST하도록 할 수 있습니다.
작업을 제출할 때 공개된 HTTPS webhookUrl(및 선택적 webhookSecret)을 전달합니다. 엔터프라이즈 키는 이 값들을 본문 최상위에서 읽고, 개인 키는 options에서 읽습니다.
webhookSecret을 설정하면 각 전송에 X-Webhook-Signature 헤더가 포함됩니다——원본 JSON 페이로드의 HMAC-SHA256을 16진수로 인코딩한 값입니다. 여러분의 secret으로 다시 계산해 비교한 뒤에 페이로드를 신뢰하십시오. 전송에는 X-Idempotency-Key(taskId + status)도 함께 오므로 중복을 무시할 수 있습니다.
{
"input": { "imageUrl": "https://example.com/photo.png" },
"webhookUrl": "https://your-server.com/hook",
"webhookSecret": "whsec_your_secret"
}webhook 검증(Node.js)
import crypto from "node:crypto";
function verify(rawBody, signature, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
return signature === expected;
}
app.post("/hook", (req, res) => {
const sig = req.header("X-Webhook-Signature");
if (!verify(req.rawBody, sig, process.env.WEBHOOK_SECRET)) {
return res.status(401).end();
}
// req.body: { taskId, serviceCode, status, ... }
res.status(200).end();
});AI 작업은 크레딧을 소비합니다. 개인 키와 엔터프라이즈 키에는 동일한 가격이 적용되며, 다른 것은 지갑뿐입니다: 개인 키는 개인 크레딧을, 엔터프라이즈 키는 조직의 풀을 사용합니다.
크레딧은 작업이 접수될 때 예약되고, 완료되면 정확한 금액으로 정산됩니다. 작업이 실패하거나 취소되면 예약분이 전액 환불됩니다——실패한 작업에 대해 과금되는 일은 없습니다.
비용은 서비스에 따라 다릅니다. 어떤 서비스는 요청당 정액을 부과하고, 어떤 서비스는 출력 해상도(픽셀당)나 가장 긴 변에 따라 비례합니다. 작업을 실행하기 전에 cost 엔드포인트를 호출하면 정확한 요금을 미리 확인할 수 있습니다.
curl -X POST https://api.vberai.com/api/ai/services/super-matting/cost \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"width": 1024, "height": 768}}'{
"success": true,
"data": {
"estimatedCredits": 10,
"pricingType": "custom",
"pricingMode": "dimension",
"sufficient": true
}
}속도 제한은 키 유형에 따라 다릅니다. 둘 다 백엔드에서 서비스별로 구성됩니다——아래 값은 고정된 숫자가 아니라 메커니즘을 설명합니다.
개인 키는 서비스별로 구성되는 분당 및 일당 요청 수로 제한됩니다. 각 응답에는 아래 헤더가 실려 있어 호출 속도를 조절할 수 있습니다.
| 헤더 | 설명 |
|---|---|
X-RateLimit-Limit-Minute | 분당 허용되는 요청 수. |
X-RateLimit-Remaining-Minute | 현재 분 단위 창에서 남은 요청 수. |
X-RateLimit-Limit-Day | 일당 허용되는 요청 수. |
X-RateLimit-Remaining-Day | 현재 일 단위 창에서 남은 요청 수. |
엔터프라이즈 키는 요청 속도가 아니라 조직에서 동시에 실행할 수 있는 작업 수로 제한됩니다. 한도는 조직별 맞춤(무제한일 수도 있음)이며, 초과하면 429 CONCURRENCY_LIMIT_EXCEEDED가 반환됩니다. 엔터프라이즈 응답에는 X-RateLimit 헤더가 실리지 않습니다.
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 59
X-RateLimit-Limit-Day: 2000
X-RateLimit-Remaining-Day: 1997모든 응답에는 success, message, timestamp가 포함됩니다. 실패 시에는 오류 코드가 문제를 식별합니다. 메시지 텍스트가 아니라 코드로 분기하십시오——메시지는 바뀔 수 있고 영어로만 제공됩니다.
코드의 위치
| 상태 | 의미 |
|---|---|
| 200 | 성공——결과를 인라인으로 반환. |
| 202 | 접수됨——비동기 태스크가 생성되었습니다. 폴링하거나 webhook을 기다립니다. |
| 400 | 잘못된 요청——입력이 유효하지 않거나, 서비스의 실행 모드에 맞지 않는 엔드포인트. |
| 401 | 인증 실패——API 키가 없거나 형식이 잘못되었거나 유형이 맞지 않음. |
| 402 | 결제 필요——크레딧 부족. |
| 403 | 금지됨——해당 키나 계정은 이 서비스를 사용할 수 없습니다. |
| 404 | 찾을 수 없음——알 수 없는 태스크이거나, 본인의 태스크가 아님. |
| 429 | 요청이 너무 많음——속도 또는 동시 실행 한도 초과. |
| 500 | 서버 오류——다시 시도하십시오. 작업(있는 경우)은 환불됩니다. |
| 코드 | 위치 | 의미 |
|---|---|---|
INSUFFICIENT_CREDITS | errorCode | 작업에 필요한 개인 크레딧이 부족합니다. |
INSUFFICIENT_ORG_CREDITS | errorCode | 작업에 필요한 조직 크레딧이 부족합니다. |
ORG_API_KEY_REQUIRED | data.code | 이 엔드포인트에는 엔터프라이즈 API 키(X-API-Key)가 필요합니다. |
INVALID_ORG_API_KEY | data.code | 엔터프라이즈 키가 없거나 형식이 잘못되었거나 취소되었습니다. |
INVALID_API_KEY | data.code | API 키 형식이 유효하지 않습니다——대개 개인 라우트를 엔터프라이즈 키로 호출한 경우(또는 그 반대)입니다. |
API_SERVICE_NOT_ALLOWED | errorCode | 귀하의 조직은 이 서비스 사용을 승인받지 않았습니다. |
ORG_DISABLED | data.code | 조직 계정이 비활성화되었습니다. |
CONCURRENCY_LIMIT_EXCEEDED | errorCode | 조직의 동시 실행 작업이 너무 많습니다. |
SERVICE_NOT_EXTERNALLY_ACCESSIBLE | errorCode | 이 서비스는 외부 API로 제공되지 않습니다. |
TASK_NOT_FOUND | errorCode | 이 키에 해당하는 태스크가 없습니다. |
{
"success": false,
"errorCode": "INSUFFICIENT_ORG_CREDITS",
"message": "Insufficient organization credits",
"timestamp": "2026-01-15T10:30:00.000Z"
}서비스별 구체적인 요청 및 응답 세부 정보입니다. 예시는 두 키 유형을 모두 보여줍니다——보유한 키에 맞는 탭을 선택하십시오. 이들이 전제로 하는 개념(폴링, 상태, 오류, 과금)은 위의 가이드를 참조하십시오.
아래 두 서비스는 전체 문서가 제공됩니다. 여러분의 키가 호출할 수 있는 완전하고 실시간인 서비스 목록——및 각 서비스의 매개변수 사양——은 카탈로그 엔드포인트에 질의하십시오. 가용성은 플랜과 조직 승인 상황에 따라 달라지므로, 이것이 신뢰할 수 있는 출처입니다.
| 엔드포인트 | 설명 |
|---|---|
GET /ai/services | 여러분의 키가 접근할 수 있는 서비스를 나열합니다. |
GET /ai/external/services/{code}/spec | 한 서비스의 매개변수 사양을 가져옵니다. |
curl https://api.vberai.com/api/ai/services \
-H "X-API-Key: YOUR_API_KEY"