VberAI 개발자 API

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

API v1
안정 버전

API 문서

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

슈퍼 매팅

super-matting

피사체를 배경에서 분리하여 깔끔한 매팅 결과를 반환하는 고품질 컷아웃입니다. 비동기——제출한 뒤 폴링하거나 webhook을 기다립니다.

가격

출력의 가장 긴 변으로 가격이 매겨집니다(치수 단계——예: 512 px는 2 크레딧, 1024 px는 10 크레딧). 작업을 실행하기 전에 /cost 엔드포인트를 호출해 정확한 금액을 확인하십시오.

매개변수

매개변수타입필수설명
source_typestring예"url"(input_value가 공개 http(s) 이미지 URL) 또는 "base64"(input_value가 base64 문자열 또는 data: URL) 중 하나.
input_valuestring예소스 이미지: source_type이 "url"이면 http(s) URL, "base64"이면 base64 이미지 데이터.
widthnumber예목표 너비(픽셀, 64–2048).
heightnumber예목표 높이(픽셀, 64–2048).
seednumber아니요선택 사항. 재현 가능한 출력을 위한 고정 정수 seed. 생략하면 랜덤 seed가 사용됩니다.

폴링 및 결과

비동기 작업은 taskId를 반환합니다. 상태가 종료 값이 될 때까지 태스크를 폴링한 뒤 결과를 읽습니다. 어떤 라우트를 폴링하는지는 키 유형에 따라 달라집니다——이것이 가장 중요하게 정확히 지켜야 할 부분입니다.

동작개인 키엔터프라이즈 키
태스크 상태 폴링GET /ai/tasks/{taskId}GET /ai/org-services/tasks/{taskId}
새 다운로드 URL 재서명상태 응답에서 읽기GET /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는 개인 키 전용입니다.

태스크는 이 값들을 거쳐 이동합니다. 종료 상태에 도달하면 폴링을 멈추십시오: completed, failed, cancelled 또는 timeout.

createdqueueddispatchingsubmittedprocessingcompletedfailedcancelledtimeout

status가 completed이면 result.assets가 출력 이미지를 담습니다. 각 asset에는 url(만료되는 사전 서명 다운로드 링크), mimeType, index가 있으며, width, height, size, expiresAt은 가능한 경우에 나타납니다. URL은 신속히 가져오십시오——엔터프라이즈 키는 /outputs 엔드포인트에서 새 링크를 다시 요청할 수 있습니다.

완료되면 result.assets가 매팅 출력 이미지를 담습니다.

완료된 태스크

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

Webhook

작업을 제출할 때 공개된 HTTPS webhookUrl(및 선택적 webhookSecret)을 전달합니다. 엔터프라이즈 키는 이 값들을 본문 최상위에서 읽고, 개인 키는 options에서 읽습니다.

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

POST/ai/services/super-matting/execute
bash
curl -X POST https://api.vberai.com/api/ai/services/super-matting/execute \
  -H "X-API-Key: vber_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "source_type": "url",
      "input_value": "https://example.com/photo.png",
      "width": 1024,
      "height": 768
    }
  }'
bash
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"