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 で受け取れるタスクを返します。
2 種類のキー
個人キーは個々の開発者向け、エンタープライズキーは組織のサーバー間利用向けです。
予測可能な課金
クレジットは送信時に予約され、成功時に確定します。失敗したジョブは自動的に返金されます。
# 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 キーによって認証されます。キーには 2 種類あり、それぞれ異なるルートを使用します——キーの種類に対して誤ったルートを選ぶことが、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
}
}レート制限はキーの種類によって異なります。どちらもバックエンドでサービスごとに設定されます——以下の値は仕組みを説明するものであり、固定の数値ではありません。
個人キーは、サービスごとに設定される 1 分あたり・1 日あたりのリクエスト数で制限されます。各レスポンスには以下のヘッダーが付くため、呼び出しのペースを調整できます。
| ヘッダー | 説明 |
|---|---|
X-RateLimit-Limit-Minute | 1 分あたりに許可されるリクエスト数。 |
X-RateLimit-Remaining-Minute | 現在の 1 分間のウィンドウで残っているリクエスト数。 |
X-RateLimit-Limit-Day | 1 日あたりに許可されるリクエスト数。 |
X-RateLimit-Remaining-Day | 現在の 1 日のウィンドウで残っているリクエスト数。 |
エンタープライズキーはリクエストレートではなく、組織で同時に実行できるジョブ数で制限されます。上限は組織ごとにカスタム(無制限の場合もあります)で、超過すると 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"
}サービスごとの具体的なリクエストとレスポンスの詳細です。例では両方のキーの種類を示しています——お持ちのキーに合わせてタブを選んでください。それらが前提とする概念(ポーリング、ステータス、エラー、課金)については、上記のガイドを参照してください。
以下の 2 つのサービスは全文が文書化されています。あなたのキーが呼び出せる完全でライブなサービス一覧——および各サービスのパラメータ仕様——については、カタログエンドポイントに問い合わせてください。可用性はプランと組織の承認状況によって変わるため、これが信頼できる情報源です。
| エンドポイント | 説明 |
|---|---|
GET /ai/services | あなたのキーがアクセスできるサービスを一覧表示します。 |
GET /ai/external/services/{code}/spec | 1 つのサービスのパラメータ仕様を取得します。 |
curl https://api.vberai.com/api/ai/services \
-H "X-API-Key: YOUR_API_KEY"