VberAI 開発者 API

VberAI は AI スーパー切り抜きなどの機能をアプリ、ゲーム、自動化パイプラインに組み込める RESTful HTTP API を提供します。API キーと署名による認証、統一されたエラーコード、クレジット課金で従量制です。

API v1
安定版

API ドキュメント

画像の生成、背景の除去、VberAI の AI パイプラインの実行を、個人またはエンタープライズの API キーで HTTP から直接行えます。

はじめに

VberAI API は、studio を支えるのと同じ AI パイプライン——背景除去、スーパーマッティング、画像生成など——をシンプルな HTTP エンドポイントとして公開します。API キーで認証し、ジョブを送信して、結果を読み戻すか webhook で受け取ります。

統一されたリクエスト形式

どのサービスも { input } ボディを受け取り、ポーリングまたは webhook で受け取れるタスクを返します。

2 種類のキー

個人キーは個々の開発者向け、エンタープライズキーは組織のサーバー間利用向けです。

予測可能な課金

クレジットは送信時に予約され、成功時に確定します。失敗したジョブは自動的に返金されます。

仕組み

  1. 1X-API-Key ヘッダーに API キーを入れて認証します。
  2. 2JSON の { input } ボディでサービスにジョブを送信します。
  3. 3結果をインラインで読み取る(同期サービス)か、タスクをポーリングする / webhook を受け取ります(非同期サービス)。
bash
# 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"

認証と API キー

すべてのリクエストは、X-API-Key ヘッダーで送る API キーによって認証されます。キーには 2 種類あり、それぞれ異なるルートを使用します——キーの種類に対して誤ったルートを選ぶことが、401 の最も多い原因です。

API キーはパスワードと同じように扱ってください。バックエンドからのみ送信し、漏洩したらローテーションし、エンタープライズキーには利用上限を設定します。

個人キー —— 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
取得方法セルフサービス、アカウント設定組織管理者、エンタープライズポータル
課金先個人クレジット組織クレジット
制限分あたり / 日あたりのリクエスト制限組織ごとの同時実行数(カスタム)
http
X-API-Key: vber_sk_...        # personal key
X-API-Key: vber_org_sk_...    # enterprise key

ベース URL

text
https://api.vberai.com/api

リクエストと実行モード

どのサービスも、サービスのパラメータを保持する input オブジェクトを含む JSON ボディを受け取ります。結果の取得方法は、サービスの実行モードによって異なります。

同期サービス

高速なサービス(たとえばチャットやテキスト翻訳)は、同じレスポンスの中で HTTP 200 とともに結果をインラインで返します。ポーリングは不要です。

非同期サービス

より重いサービス(画像生成、マッティング、背景除去)は、taskId とともに HTTP 202 を返します。完了したらタスクをポーリングするか、webhook で結果を受け取ります。

個人キー

個人キーはサービスごとに単一のエンドポイントを使用します:POST /ai/services/{code}/execute。同期サービスでは結果をインライン(200)で、非同期サービスではタスク(202)を返します——どちらも同じエンドポイントです。

エンタープライズキー

エンタープライズキーは 2 つのエンドポイントを使用します:同期サービスは /execute、非同期サービスは /execute-async です。誤ったほうを呼び出すと 400 が返り、どのエンドポイントを使うべきかが示されます。
json
{
  "input": {
    "imageUrl": "https://example.com/photo.png"
  },
  "webhookUrl": "https://your-server.com/hook"
}
bash
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 ルートをポーリングする必要があります

エンタープライズキー(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 エンドポイントから新しいリンクを再取得できます。

bash
# 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"

完了したタスク

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

冪等性

冪等性により、ネットワークエラーの後で送信を安全に再試行しても、重複したジョブを作成したり二重に課金されたりすることがありません。

エンタープライズキー

/execute-async では、任意で Idempotency-Key ヘッダー(あなたが生成する最大 200 文字の値——UUID が理想的)を送信できます。同じキーで再試行すると、新しいタスクを作成せずに元のタスクを返します。サーバーは重複排除のみを行い、キーを代わりに生成することはありません。

個人キー

個人 API キーのリクエストは、現在のところ冪等キーをサポートしていません。前のリクエストがタスクを作成しなかったことを確認してから(受け取った taskId でポーリング)再試行してください。

http
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Webhook

ポーリングの代わりに、タスクが終端ステータスに達したときに VberAI が結果をあなたのサーバーへ POST するようにできます。

Webhook の設定

ジョブを送信する際に、公開された HTTPS の webhookUrl(および任意の webhookSecret)を渡します。エンタープライズキーはこれらをボディのトップレベルから読み取り、個人キーは options から読み取ります。

署名の検証

webhookSecret を設定した場合、各配信には X-Webhook-Signature ヘッダーが含まれます——生の JSON ペイロードの HMAC-SHA256 を 16 進エンコードしたものです。あなたの secret で再計算して比較し、確認できてからペイロードを信頼してください。配信には X-Idempotency-Key(taskId + status)も付くため、重複を無視できます。

失敗した配信は、バックオフを伴って数回再試行されます。受領を知らせるには 2xx で応答してください。
json
{
  "input": { "imageUrl": "https://example.com/photo.png" },
  "webhookUrl": "https://your-server.com/hook",
  "webhookSecret": "whsec_your_secret"
}

webhook を検証する(Node.js)

javascript
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 エンドポイントを呼び出すと、正確な料金をプレビューできます。

  • •リクエストごと——呼び出しごとに定額。
  • •ピクセルごと——出力の 幅 × 高さ に応じて増減。
  • •寸法ごと——出力の最長辺で価格が決まります。
bash
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}}'
json
{
  "success": true,
  "data": {
    "estimatedCredits": 10,
    "pricingType": "custom",
    "pricingMode": "dimension",
    "sufficient": true
  }
}

レート制限

レート制限はキーの種類によって異なります。どちらもバックエンドでサービスごとに設定されます——以下の値は仕組みを説明するものであり、固定の数値ではありません。

個人キー —— リクエストレート

個人キーは、サービスごとに設定される 1 分あたり・1 日あたりのリクエスト数で制限されます。各レスポンスには以下のヘッダーが付くため、呼び出しのペースを調整できます。

ヘッダー説明
X-RateLimit-Limit-Minute1 分あたりに許可されるリクエスト数。
X-RateLimit-Remaining-Minute現在の 1 分間のウィンドウで残っているリクエスト数。
X-RateLimit-Limit-Day1 日あたりに許可されるリクエスト数。
X-RateLimit-Remaining-Day現在の 1 日のウィンドウで残っているリクエスト数。
X-RateLimit-Reset ヘッダーはありません。429 の場合、レスポンスボディに retryAfter と resetIn が含まれます。

エンタープライズキー —— 同時実行

エンタープライズキーはリクエストレートではなく、組織で同時に実行できるジョブ数で制限されます。上限は組織ごとにカスタム(無制限の場合もあります)で、超過すると 429 CONCURRENCY_LIMIT_EXCEEDED が返ります。エンタープライズのレスポンスには X-RateLimit ヘッダーは付きません。

http
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 59
X-RateLimit-Limit-Day: 2000
X-RateLimit-Remaining-Day: 1997

エラー

すべてのレスポンスには success、message、timestamp が含まれます。失敗時には、エラーコードが問題を示します。メッセージのテキストではなくコードで分岐してください——メッセージは変わる可能性があり、英語のみです。

コードの場所

エンタープライズのエラーは一貫しています:認証の問題はコードを data.code に、サービスと課金の問題はトップレベルの errorCode に置きます。個人のエラーはエンドポイントによって異なります(トップレベルの errorCode、data.code、または errors.code)——各コードについて示されたフィールドを読み取ってください。

HTTP ステータスコード

ステータス意味
200成功——結果をインラインで返却。
202受理——非同期タスクが作成されました。ポーリングするか webhook を待ちます。
400不正なリクエスト——入力が無効、またはサービスの実行モードに対して誤ったエンドポイント。
401認証エラー——API キーが欠落、不正な形式、または種類の誤り。
402支払いが必要——クレジット不足。
403禁止——そのキーまたはアカウントはこのサービスを使用できません。
404見つかりません——不明なタスク、またはあなたのものではないタスク。
429リクエストが多すぎます——レートまたは同時実行の上限を超過。
500サーバーエラー——再試行してください。ジョブ(ある場合)は返金されます。

よくあるエラーコード

コード場所意味
INSUFFICIENT_CREDITSerrorCodeジョブに必要な個人クレジットが不足しています。
INSUFFICIENT_ORG_CREDITSerrorCodeジョブに必要な組織クレジットが不足しています。
ORG_API_KEY_REQUIREDdata.codeこのエンドポイントにはエンタープライズ API キー(X-API-Key)が必要です。
INVALID_ORG_API_KEYdata.codeエンタープライズキーが欠落、不正な形式、または取り消されています。
INVALID_API_KEYdata.codeAPI キーの形式が無効です——多くの場合、個人ルートをエンタープライズキーで呼び出した(またはその逆)ことが原因です。
API_SERVICE_NOT_ALLOWEDerrorCodeあなたの組織はこのサービスの利用を承認されていません。
ORG_DISABLEDdata.code組織アカウントが無効化されています。
CONCURRENCY_LIMIT_EXCEEDEDerrorCode組織の同時実行ジョブが多すぎます。
SERVICE_NOT_EXTERNALLY_ACCESSIBLEerrorCodeこのサービスは外部 API では利用できません。
TASK_NOT_FOUNDerrorCodeこのキーに該当するタスクはありません。
json
{
  "success": false,
  "errorCode": "INSUFFICIENT_ORG_CREDITS",
  "message": "Insufficient organization credits",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

API ドキュメント

サービスごとの具体的なリクエストとレスポンスの詳細です。例では両方のキーの種類を示しています——お持ちのキーに合わせてタブを選んでください。それらが前提とする概念(ポーリング、ステータス、エラー、課金)については、上記のガイドを参照してください。

利用可能なサービス

以下の 2 つのサービスは全文が文書化されています。あなたのキーが呼び出せる完全でライブなサービス一覧——および各サービスのパラメータ仕様——については、カタログエンドポイントに問い合わせてください。可用性はプランと組織の承認状況によって変わるため、これが信頼できる情報源です。

エンドポイント説明
GET /ai/servicesあなたのキーがアクセスできるサービスを一覧表示します。
GET /ai/external/services/{code}/spec1 つのサービスのパラメータ仕様を取得します。
bash
curl https://api.vberai.com/api/ai/services \
  -H "X-API-Key: YOUR_API_KEY"