VberAI 개발자 API

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

API v1
안정 버전

API 문서

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

배경 제거

ai-image-bg-remove

이미지에서 배경을 제거하고 배경이 투명한 컷아웃을 반환합니다. 비동기——제출한 뒤 폴링하거나 webhook을 기다립니다.

가격

이미지당 정액 과금입니다. 정확한 금액은 /cost 엔드포인트를 호출하십시오.

매개변수

매개변수타입필수설명
imageUrlstring예처리할 이미지의 공개 http(s) URL. 이 서비스가 받는 유일한 입력입니다——base64나 source_type은 받지 않습니다.
widthnumber아니요선택 사항. 소스 해상도를 감지할 수 없을 때 과금 면적의 폴백으로만 사용되며, 출력은 바뀌지 않습니다.
heightnumber아니요선택 사항. 소스 해상도를 감지할 수 없을 때 과금 면적의 폴백으로만 사용되며, 출력은 바뀌지 않습니다.

폴링 및 결과

비동기 작업은 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": "ai-image-bg-remove",
    "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/ai-image-bg-remove/execute
bash
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"}}'
bash
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"