VberAI 開発者 API
VberAI は AI スーパー切り抜きなどの機能をアプリ、ゲーム、自動化パイプラインに組み込める RESTful HTTP API を提供します。API キーと署名による認証、統一されたエラーコード、クレジット課金で従量制です。
VberAI は AI スーパー切り抜きなどの機能をアプリ、ゲーム、自動化パイプラインに組み込める RESTful HTTP API を提供します。API キーと署名による認証、統一されたエラーコード、クレジット課金で従量制です。
画像の生成、背景の除去、VberAI の AI パイプラインの実行を、個人またはエンタープライズの API キーで HTTP から直接行えます。
フラットな UI 画像を入れると編集可能なレイヤーが返ります。背景 PNG、要素ごとの透過 PNG、そして各レイヤーの名前・種別・位置・サイズ・重ね順を示す JSON リストです。1 枚の静止画を編集可能なマルチレイヤーのシーン要素に分解し、テキストは編集可能なまま保ちます。UI シーンの自動分解とデザイン復元に適しています。
| アクション | 個人キー | エンタープライズキー |
|---|---|---|
| 送信 | POST /ai/tasks | POST /ai/org-services/ai-layer-split/execute-async |
| タスクのステータスをポーリング | GET /ai/tasks/{taskId} | GET /ai/org-services/tasks/{taskId} |
| 新しいダウンロード URL を再署名 | GET /ai/tasks/{taskId}/outputs | GET /ai/org-services/tasks/{taskId}/outputs |
エンタープライズキーは /ai/org-services ルートをポーリングする必要があります
サービスパラメータは 2 種類のキーで完全に同一で、外側のラッパーだけが異なります。
| フィールド | 個人キー | エンタープライズキー |
|---|---|---|
| 下記のサービスパラメータ。 | serviceCode + inputs | input |
webhookUrl | 任意 | 任意 |
webhookSecret | 任意 | 任意 |
個人キー
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
messages | array | いずれか | 元画像を運ぶ会話配列。content[] に { "type": "image_url", "image_url": { "url": "…" } } を 1 つ含めてください。URL は公開 https でも インライン data: URI でも構いません。 |
referenceImage | string | いずれか | 元画像の簡略指定。公開 https URL または インライン data: URI を渡します。messages[] の代わりに使えます。 |
referenceWidth | number | いいえ | 元画像の宣言幅(ピクセル)。送信時の料金ティア判定にのみ使われ、実サイズは画像から計測されます。 |
referenceHeight | number | いいえ | 元画像の宣言高さ(ピクセル)。用途は referenceWidth と同じです。 |
imageConfig | object | いいえ | 将来の生成オプション用の予約領域で、現在は無視されます。 |
画像を自前でホスティングせず、data: URI としてリクエストに直接埋め込めます。プラットフォームがサーバー側に保存し、生成した URL をパイプラインへ渡すため、他の手順は変わりません。
{
"referenceImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
"referenceWidth": 1295,
"referenceHeight": 726
}/ai/taskscurl -X POST https://api.vberai.com/api/ai/tasks \
-H "X-API-Key: vber_sk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"serviceCode": "ai-layer-split",
"inputs": {
"messages": [
{
"role": "user",
"content": [
{ "type": "image_url", "image_url": { "url": "https://example.com/lobby.png" } }
]
}
],
"referenceWidth": 1295,
"referenceHeight": 726
},
"webhookUrl": "https://your-server.com/hook",
"webhookSecret": "whsec_your_secret"
}'送信レスポンス — HTTP 201
{
"success": true,
"message": "Created",
"data": {
"taskId": "6a9db1471ef5f25400621411",
"taskToken": "510932d23b39a0176837a3adfd6f64a773bc85f984417a7d6bcde08108494d30",
"status": "queued",
"estimatedCredits": 150,
"message": "Task queued for processing"
},
"timestamp": "2026-09-06T18:30:31.837Z"
}status が completed または failed になるまでポーリングします。タスク記録とファイルは 7 日間保持されます。
タスクはこれらの値を経て遷移します。終端ステータスに達したらポーリングを停止してください:completed、failed、cancelled、timeout。
| フィールド | 説明 |
|---|---|
taskId | タスク識別子。ポーリング・成果物取得・webhook の突き合わせに使います。 |
serviceCode | 常に ai-layer-split。 |
status | queued · processing · completed · failed · cancelled · timeout。 |
progress | バックエンドが報告する大まかな進捗。無い場合は null。 |
provider | 実行チャネル。常に external と報告されます。 |
hasResult | result が揃うと true になります。 |
error | 失敗理由。正常時は null。 |
createdAt · startedAt · completedAt | 作成・実行開始・完了の時刻(ISO 8601、UTC)。 |
expiresAt | タスク記録とファイルが削除される時刻。完了から 7 日後です。 |
creditsEstimated · creditsActual | 送信時に確保したポイントと完了時に実際に消費したポイント。成功時は一致し、失敗時は全額返還されます。 |
outputCount | 返された成果物の数。 |
result | 下記の結果オブジェクト。完了後に現れます。 |
outputs エンドポイントは同じ result を、新しく署名し直したダウンロード URL 付きで返します。URL が失効したら再度呼び出してください。
{
"success": true,
"data": {
"taskId": "6a9db1431ef5f254006213e0",
"status": "completed",
"result": { "type": "images", "assets": [ … ], "text": "{ … }" },
"completedAt": "2026-09-06T18:32:26.326Z"
}
}webhookUrl を設定すると、ポーリングと同じ内容が POST で通知されます。webhookSecret を設定すると検証用の署名ヘッダーが付きます。
webhookSecret を設定した場合、各配信には X-Webhook-Signature ヘッダーが含まれます——生の JSON ペイロードの HMAC-SHA256 を 16 進エンコードしたものです。あなたの secret で再計算して比較し、確認できてからペイロードを信頼してください。配信には X-Idempotency-Key(taskId + status)も付くため、重複を無視できます。
Webhook のペイロード
{
"taskId": "6a9db1431ef5f254006213e0",
"serviceCode": "ai-layer-split",
"status": "completed",
"timestamp": "2026-09-06T18:32:26.401Z",
"result": {
"type": "images",
"assets": [ { "index": 0, "name": "Lbg", "url": "https://assets.vberai.org/…/0.png?<signed-query>", "mimeType": "image/png", "size": 5067542, "sha256": "7ceb4dad…" }, … ],
"text": "{\"imageSize\":{\"width\":1295,\"height\":726},\"nodes\":[…]}"
}
}Webhook · 失敗時
{
"taskId": "6a9db1431ef5f254006213e0",
"serviceCode": "ai-layer-split",
"status": "failed",
"timestamp": "2026-09-06T18:32:26.401Z",
"error": { "code": "EXECUTION_ERROR", "message": "Task processing failed" }
}タスク状態を取得
/ai/tasks/{taskId}curl https://api.vberai.com/api/ai/tasks/{taskId} \
-H "X-API-Key: vber_sk_YOUR_KEY"成果物を取得
/ai/tasks/{taskId}/outputscurl https://api.vberai.com/api/ai/tasks/{taskId}/outputs \
-H "X-API-Key: vber_sk_YOUR_KEY"result は 2 つの部分から成ります。assets[] のレイヤー画像と、text に JSON 文字列で入ったレイヤーリストです。assets[].name は各レイヤーの id と 1 対 1 で対応します。
| フィールド | 型 | 説明 |
|---|---|---|
index | number | assets 配列内の位置。 |
name | string | レイヤー id。レイヤーツリーの対応ノードの id と一致し、画像と配置情報を結び付ける鍵になります。 |
url | string | 署名付きダウンロード URL。クエリ文字列を削らずそのまま使ってください。 |
mimeType | "image/png" | 常にアルファチャンネル付きの image/png。 |
size | number | ファイルサイズ(バイト)。 |
sha256 | string | ファイルの SHA-256。整合性確認や重複排除に使えます。 |
s3Key | string | 内部オブジェクトキー。参考情報です。 |
id はサーバーが割り当て、同一タスク内では変わりません。接頭辞がレイヤーの性質を表します。
| 値 | 意味 |
|---|---|
Lbg | 背景 PNG:検出したすべての要素を取り除き、空いた部分を描き直した画像全体です。タスクごとに 1 枚で、いちばん下のレイヤーになります。imageSize より大きく返ることがあるため、配置するサイズに合わせて拡大縮小してください。 |
A001, A002, … | 画像要素ごとに 1 枚の PNG で、リスト順に採番されます。背景は透過で、他の要素に隠れていた部分は補完済みです。ピクセルサイズは box × imageSize です。 |
T001, T002, … | テキスト要素。意図的に画像は付きません。代わりに正確な文字列と書式が得られるので、実際のテキストとして再現できます。 |
| group | グループ項目。画像はなく、どのレイヤーが同じまとまりかを示すだけです。 |
完了したタスク
{
"success": true,
"data": {
"taskId": "6a9db1431ef5f254006213e0",
"serviceCode": "ai-layer-split",
"status": "completed",
"progress": null,
"provider": "external",
"hasResult": true,
"error": null,
"createdAt": "2026-09-06T18:30:27.398Z",
"startedAt": "2026-09-06T18:30:29.012Z",
"completedAt": "2026-09-06T18:32:26.326Z",
"expiresAt": "2026-09-13T18:32:26.326Z",
"creditsEstimated": 150,
"creditsActual": 150,
"outputCount": 23,
"result": {
"type": "images",
"assets": [
{
"index": 0,
"url": "https://assets.vberai.org/tmp/user-assets/6a76f458…/task_6a9db143…_background/0.png?<signed-query>",
"mimeType": "image/png",
"s3Key": "tmp/user-assets/6a76f458…/task_6a9db143…_background/0.png",
"size": 5067542,
"sha256": "7ceb4dad585d2c60368e35c994ea53819b45f29f84fa5ec36704e9b3794a5f5e",
"name": "Lbg"
},
{
"index": 1,
"url": "https://assets.vberai.org/ai-deliveries/6a76f458…/task_6a9db143…/A001-ab405a4a….png?<signed-query>",
"mimeType": "image/png",
"s3Key": "ai-deliveries/6a76f458…/task_6a9db143…/A001-ab405a4a….png",
"size": 73117,
"sha256": "ab405a4a607a7c9e95bd5dba0150f84743c73362f482bbeb990fc4687c90055e",
"name": "A001"
},
… 21 more "A002" … "A022" assets …
],
"text": "{\"imageSize\":{\"width\":1295,\"height\":726},\"nodes\":[{\"id\":\"Lbg\",…},{\"id\":\"A001\",…},…]}"
}
}
}result.text は JSON 文字列なので、まず解析してください。各レイヤーの名前・種別・位置・サイズ・グループ・重ね順が並んでいます。
| フィールド | 型 | 説明 |
|---|---|---|
imageSize | { width, height } | 解析した画像のピクセルサイズ。すべての box はこれに対する比率です。これ(または任意のサイズ)を掛けるとピクセルになります。 |
nodes | LayerNode[] | 全レイヤーのフラットな配列。グループは parentId、重ね順は paintOrder で表され、配列自体の順序に意味はありません。 |
| フィールド | 型 | 説明 |
|---|---|---|
id | string | レイヤー id。対応する assets[].name と同一です(Lbg、A001、T001 など)。レイヤーと PNG の対応付けに使います。 |
name | string | AI が推定した読みやすい名前(例: join_room_card)。説明的ですが一意とは限りません。キーには id、表示には name を使ってください。 |
kind | string | レイヤー種別。下表を参照してください。 |
box | [x, y, w, h] | 位置とサイズを [x, y, 幅, 高さ] で表し、imageSize に対する比率です。原点は左上。imageSize を掛けるとピクセルになります。 |
parentId | string | null | 所属するグループの id。ルート階層では null。 |
paintOrder | number | 同じ親を持つレイヤー間の重ね順。昇順で奥から手前です。背景は -1。 |
occluded | boolean | 他の要素に隠れていた部分があり、補完で再構成した場合に true。 |
instances | [x, y, w, h][] | 同じ要素が繰り返される場合の追加位置。追加の画像を要求せず、同じ PNG をこれらのボックスに配置してください。 |
text | object | テキスト書式。kind が text のときだけ現れます。 |
| 値 | 意味 |
|---|---|
background | 補完済みの背景。1 枚だけで最初に描画します。 |
group | 入れ子のためのコンテナ。画像は持ちません。 |
ui | パネル・カード・ボタンなどの UI 面。PNG が付きます。 |
icon | 小さなアイコン。PNG が付き、扱いは ui と同じです。 |
text | プログラムテキスト。PNG は無く、編集可能テキストとして再現します。 |
| フィールド | 型 | 説明 |
|---|---|---|
text | string | 画像から読み取った文字列。元の言語のままです。 |
fontSizePct | number | 字形の高さを imageSize.height に対する比率で表します。使用する高さを掛けるとピクセルのフォントサイズになります。 |
color | "#RRGGBB" | 字形の塗り色。 |
fontWeight | 100–900 | 数値のフォントウェイト。 |
italic | boolean | 斜体かどうか。 |
align | "LEFT" | "CENTER" | "RIGHT" | ボックス内での水平方向の揃え。 |
fontFamily | string | 推奨フォントファミリー。利用できない場合は自前の既定フォントにフォールバックしてください。 |
strokeColor | "#RRGGBB" | 字形の縁取り色(縁取りがある場合)。 |
strokeWidthPct | number | 縁取りの太さを imageSize.height に対する比率で表した値。 |
shadow | { color, dxPct, dyPct, blurPct } | ドロップシャドウ。色と、imageSize の幅・高さに対する比率で表したオフセットとぼかし。 |
レイヤーリスト(抜粋)
{
"imageSize": { "width": 1295, "height": 726 },
"nodes": [
{ "id": "Lbg", "name": "background", "kind": "background", "box": [0, 0, 1, 1], "parentId": null, "paintOrder": -1, "occluded": false },
{ "id": "A001", "name": "player_info_bg", "kind": "ui", "box": [0.0026, 0, 0.2644, 0.1322], "parentId": null, "paintOrder": 1, "occluded": false },
{ "id": "A005", "name": "player_avatar", "kind": "ui", "box": [0.0108, 0.0069, 0.068, 0.1157], "parentId": null, "paintOrder": 5, "occluded": false },
{ "id": "A013", "name": "join_room_card", "kind": "ui", "box": [0.3153, 0.2546, 0.1825, 0.6906], "parentId": null, "paintOrder": 13, "occluded": false },
{
"id": "T001", "name": "player_name", "kind": "text",
"box": [0.0827, 0.0193, 0.1543, 0.0427], "parentId": null, "paintOrder": 18, "occluded": false,
"text": { "text": "明月清风晓星尘", "fontSizePct": 0.022, "color": "#FFFFFF", "fontWeight": 400, "align": "LEFT" }
},
{
"id": "T003", "name": "currency_1_amount", "kind": "text",
"box": [0.3614, 0.0372, 0.0533, 0.0455], "parentId": null, "paintOrder": 20, "occluded": false,
"text": {
"text": "87万", "fontSizePct": 0.0248, "color": "#FFFFFF", "fontWeight": 700, "align": "CENTER",
"strokeColor": "#5C3A21", "strokeWidthPct": 0.0028
}
},
… 23 more nodes …
]
}構造
// JSON.parse(result.text)
{
imageSize: { width, height }, // px of the analysed image
nodes: [
{
id: "Lbg" | "A001" | "T001" | "<group id>", // == asset name
name: "join_room_card", // AI-given, may repeat
kind: "background" | "group" | "ui" | "icon" | "text",
box: [x, y, w, h], // fractions 0..1 of imageSize
parentId: null | "<group id>",
paintOrder: -1 | 0 | 1 | ..., // ascending = bottom → top (siblings)
occluded: false,
instances: [[x, y, w, h]], // optional: repeated placements
text: { // only when kind === "text"
text, fontSizePct, color, fontWeight, italic, align,
fontFamily, strokeColor, strokeWidthPct,
shadow: { color, dxPct, dyPct, blurPct }
}
}
]
}位置とサイズは比率なので、同じリストがどのピクセルサイズでもそのまま使えます。
配置リストの作成
const { result } = task; // from polling, outputs or the webhook
const tree = JSON.parse(result.text);
const { width: W, height: H } = tree.imageSize; // reference pixel size
const png = Object.fromEntries(result.assets.map((a) => [a.name, a.url]));
// 1) box fractions -> pixels, at whatever size you work at
const px = ([x, y, w, h]) => ({ x: x * W, y: y * H, width: w * W, height: h * H });
// 2) back -> front within each parent
const childrenOf = (parentId) =>
tree.nodes
.filter((n) => n.parentId === parentId)
.sort((a, b) => a.paintOrder - b.paintOrder);
// 3) flatten into a placement list your app can consume
function collect(parentId = null, out = []) {
for (const n of childrenOf(parentId)) {
if (n.kind === "group") { collect(n.id, out); continue; }
for (const box of [n.box, ...(n.instances ?? [])]) {
out.push({
id: n.id,
name: n.name, // e.g. "join_room_card"
kind: n.kind, // background | ui | icon | text
...px(box), // x, y, width, height in px
order: n.paintOrder,
image: n.kind === "text" ? null : png[n.id],
text: n.text ?? null, // content + styling, text only
});
}
}
return out;
}
const layers = collect(); // ready to place or import
1 回の呼び出しごとの定額で、元画像の長辺に応じたティアで決まります。送信時に estimatedCredits として返り、完了時に消費されます。失敗したタスクは全額返還されます。
| ティア | 長辺 | ポイント |
|---|---|---|
1K | ≤ 1024 px | 120 |
2K | ≤ 2048 px | 180 |
4K | > 2048 px | 250 |
| 値 | 説明 |
|---|---|
2048 px | 解析前に元画像は長辺 2048 px へ縮小されます。 |
300 | 1 枚あたり最大 300 要素まで検出します。 |
20 MB | インライン base64 メディアは 1 項目 20 MB まで。 |
| 2〜3 分 | エンドツーエンドの標準所要時間。 |
| 7 日 | タスク記録とファイルの保持期間。 |
| 約 1 時間 | 署名付きダウンロード URL の有効期間。 |
送信時のエラーは同期的に返ります。実行時のエラーはタスクが failed になり error オブジェクトが付きます。
| ステータス | コード | 意味 |
|---|---|---|
| 400 | — | リクエストの形式が不正です。多くは messages[] にも referenceImage にも元画像が無いケースです。 |
| 401 | INVALID_API_KEY · INVALID_ORG_API_KEY | API キーが無いか無効です。 |
| 402 | INSUFFICIENT_CREDITS · INSUFFICIENT_ORG_CREDITS | この画像の解像度ティアに必要なポイントが不足しています。 |
| 403 | API_SERVICE_NOT_ALLOWED · ORG_DISABLED | そのキーまたは組織にこのサービスの利用権限がありません。 |
| 413 | — | インライン base64 画像が 20 MB を超えています。https URL で渡してください。 |
| 429 | RATE_LIMIT_MINUTE · RATE_LIMIT_DAY · CONCURRENCY_LIMIT_EXCEEDED | レートまたは同時実行の上限に達しました。少し待って再試行してください。 |
| failed | error.code | タスク開始後に実行が失敗しました。error.code と error.message に理由が入り、確保したポイントは全額返還されます。 |
エラーレスポンス — HTTP 400
{
"success": false,
"message": "A reference image is required: provide it as an `image_url` part inside messages[].content[], or pass `referenceImage` directly.",
"timestamp": "2026-09-06T18:30:27.398Z"
}失敗したタスク(ポーリング結果)
{
"success": true,
"data": {
"taskId": "6a9db1431ef5f254006213e0",
"serviceCode": "ai-layer-split",
"status": "failed",
"hasResult": false,
"error": { "code": "EXECUTION_ERROR", "message": "Task processing failed" },
"creditsEstimated": 150,
"creditsActual": 0,
"outputCount": 0
}
}