VberAI 開発者 API

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

API v1
安定版

API ドキュメント

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

AI レイヤー分割

フラットな UI 画像を入れると編集可能なレイヤーが返ります。背景 PNG、要素ごとの透過 PNG、そして各レイヤーの名前・種別・位置・サイズ・重ね順を示す JSON リストです。

1 枚の静止画を編集可能なマルチレイヤーのシーン要素に分解し、テキストは編集可能なまま保ちます。UI シーンの自動分解とデザイン復元に適しています。

処理の流れ

  1. 1フラット画像を送信すると taskId がすぐ返ります。処理は非同期で、通常 2〜3 分かかります。
  2. 2タスクをポーリングするか、完了時に webhook を受け取ります。
  3. 3署名付き URL から PNG をダウンロードし、result.text でレイヤーリストを読み取ります。

エンドポイント

アクション個人キーエンタープライズキー
送信POST /ai/tasksPOST /ai/org-services/ai-layer-split/execute-async
タスクのステータスをポーリングGET /ai/tasks/{taskId}GET /ai/org-services/tasks/{taskId}
新しいダウンロード URL を再署名GET /ai/tasks/{taskId}/outputsGET /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 は個人キー専用です。

リクエストの外側

サービスパラメータは 2 種類のキーで完全に同一で、外側のラッパーだけが異なります。

フィールド個人キーエンタープライズキー
下記のサービスパラメータ。serviceCode + inputsinput
webhookUrl任意任意
webhookSecret任意任意

個人キー

どちらのキーもポーリングだけで使えます。webhookUrl を省けば自分で状態を確認し、指定すれば完了時に通知が届きます。指定する場合は公開 https URL である必要があります。

サービスパラメータ

パラメータ型必須説明
messagesarrayいずれか元画像を運ぶ会話配列。content[] に { "type": "image_url", "image_url": { "url": "…" } } を 1 つ含めてください。URL は公開 https でも インライン data: URI でも構いません。
referenceImagestringいずれか元画像の簡略指定。公開 https URL または インライン data: URI を渡します。messages[] の代わりに使えます。
referenceWidthnumberいいえ元画像の宣言幅(ピクセル)。送信時の料金ティア判定にのみ使われ、実サイズは画像から計測されます。
referenceHeightnumberいいえ元画像の宣言高さ(ピクセル)。用途は referenceWidth と同じです。
imageConfigobjectいいえ将来の生成オプション用の予約領域で、現在は無視されます。
元画像は messages[](OpenAI 形式のコンテンツパート)か referenceImage のどちらかで渡します。いずれか一方が必須です。

インライン base64 画像

画像を自前でホスティングせず、data: URI としてリクエストに直接埋め込めます。プラットフォームがサーバー側に保存し、生成した URL をパイプラインへ渡すため、他の手順は変わりません。

json
{
  "referenceImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "referenceWidth": 1295,
  "referenceHeight": 726
}
インラインメディアは 1 項目あたり 20 MB まで(base64 文字列ではなくデコード後のサイズ)。これを超える画像は https URL で渡してください。
POST/ai/tasks
bash
curl -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

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

queuedprocessingcompletedfailedcancelledtimeout

タスクのフィールド

フィールド説明
taskIdタスク識別子。ポーリング・成果物取得・webhook の突き合わせに使います。
serviceCode常に ai-layer-split。
statusqueued · processing · completed · failed · cancelled · timeout。
progressバックエンドが報告する大まかな進捗。無い場合は null。
provider実行チャネル。常に external と報告されます。
hasResultresult が揃うと true になります。
error失敗理由。正常時は null。
createdAt · startedAt · completedAt作成・実行開始・完了の時刻(ISO 8601、UTC)。
expiresAtタスク記録とファイルが削除される時刻。完了から 7 日後です。
creditsEstimated · creditsActual送信時に確保したポイントと完了時に実際に消費したポイント。成功時は一致し、失敗時は全額返還されます。
outputCount返された成果物の数。
result下記の結果オブジェクト。完了後に現れます。

結果の取得

outputs エンドポイントは同じ result を、新しく署名し直したダウンロード URL 付きで返します。URL が失効したら再度呼び出してください。

json
{
  "success": true,
  "data": {
    "taskId": "6a9db1431ef5f254006213e0",
    "status": "completed",
    "result": { "type": "images", "assets": [ … ], "text": "{ … }" },
    "completedAt": "2026-09-06T18:32:26.326Z"
  }
}

Webhook

webhookUrl を設定すると、ポーリングと同じ内容が POST で通知されます。webhookSecret を設定すると検証用の署名ヘッダーが付きます。

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

Webhook のペイロード

json
{
  "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 · 失敗時

json
{
  "taskId": "6a9db1431ef5f254006213e0",
  "serviceCode": "ai-layer-split",
  "status": "failed",
  "timestamp": "2026-09-06T18:32:26.401Z",
  "error": { "code": "EXECUTION_ERROR", "message": "Task processing failed" }
}

タスク状態を取得

GET/ai/tasks/{taskId}
bash
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"

成果物を取得

GET/ai/tasks/{taskId}/outputs
bash
curl 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 で対応します。

成果物

フィールド型説明
indexnumberassets 配列内の位置。
namestringレイヤー id。レイヤーツリーの対応ノードの id と一致し、画像と配置情報を結び付ける鍵になります。
urlstring署名付きダウンロード URL。クエリ文字列を削らずそのまま使ってください。
mimeType"image/png"常にアルファチャンネル付きの image/png。
sizenumberファイルサイズ(バイト)。
sha256stringファイルの SHA-256。整合性確認や重複排除に使えます。
s3Keystring内部オブジェクトキー。参考情報です。
ダウンロード URL は短命(約 1 時間)です。失効したら outputs を再度呼んで新しい URL を取得してください。ファイル自体は 7 日間残ります。

レイヤーの命名

id はサーバーが割り当て、同一タスク内では変わりません。接頭辞がレイヤーの性質を表します。

値意味
Lbg背景 PNG:検出したすべての要素を取り除き、空いた部分を描き直した画像全体です。タスクごとに 1 枚で、いちばん下のレイヤーになります。imageSize より大きく返ることがあるため、配置するサイズに合わせて拡大縮小してください。
A001, A002, …画像要素ごとに 1 枚の PNG で、リスト順に採番されます。背景は透過で、他の要素に隠れていた部分は補完済みです。ピクセルサイズは box × imageSize です。
T001, T002, …テキスト要素。意図的に画像は付きません。代わりに正確な文字列と書式が得られるので、実際のテキストとして再現できます。
groupグループ項目。画像はなく、どのレイヤーが同じまとまりかを示すだけです。

完了したタスク

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

result.text は JSON 文字列なので、まず解析してください。各レイヤーの名前・種別・位置・サイズ・グループ・重ね順が並んでいます。

トップレベル

フィールド型説明
imageSize{ width, height }解析した画像のピクセルサイズ。すべての box はこれに対する比率です。これ(または任意のサイズ)を掛けるとピクセルになります。
nodesLayerNode[]全レイヤーのフラットな配列。グループは parentId、重ね順は paintOrder で表され、配列自体の順序に意味はありません。

レイヤー項目

フィールド型説明
idstringレイヤー id。対応する assets[].name と同一です(Lbg、A001、T001 など)。レイヤーと PNG の対応付けに使います。
namestringAI が推定した読みやすい名前(例: join_room_card)。説明的ですが一意とは限りません。キーには id、表示には name を使ってください。
kindstringレイヤー種別。下表を参照してください。
box[x, y, w, h]位置とサイズを [x, y, 幅, 高さ] で表し、imageSize に対する比率です。原点は左上。imageSize を掛けるとピクセルになります。
parentIdstring | null所属するグループの id。ルート階層では null。
paintOrdernumber同じ親を持つレイヤー間の重ね順。昇順で奥から手前です。背景は -1。
occludedboolean他の要素に隠れていた部分があり、補完で再構成した場合に true。
instances[x, y, w, h][]同じ要素が繰り返される場合の追加位置。追加の画像を要求せず、同じ PNG をこれらのボックスに配置してください。
textobjectテキスト書式。kind が text のときだけ現れます。

レイヤー種別

値意味
background補完済みの背景。1 枚だけで最初に描画します。
group入れ子のためのコンテナ。画像は持ちません。
uiパネル・カード・ボタンなどの UI 面。PNG が付きます。
icon小さなアイコン。PNG が付き、扱いは ui と同じです。
textプログラムテキスト。PNG は無く、編集可能テキストとして再現します。

テキストのプロパティ

フィールド型説明
textstring画像から読み取った文字列。元の言語のままです。
fontSizePctnumber字形の高さを imageSize.height に対する比率で表します。使用する高さを掛けるとピクセルのフォントサイズになります。
color"#RRGGBB"字形の塗り色。
fontWeight100–900数値のフォントウェイト。
italicboolean斜体かどうか。
align"LEFT" | "CENTER" | "RIGHT"ボックス内での水平方向の揃え。
fontFamilystring推奨フォントファミリー。利用できない場合は自前の既定フォントにフォールバックしてください。
strokeColor"#RRGGBB"字形の縁取り色(縁取りがある場合)。
strokeWidthPctnumber縁取りの太さを imageSize.height に対する比率で表した値。
shadow{ color, dxPct, dyPct, blurPct }ドロップシャドウ。色と、imageSize の幅・高さに対する比率で表したオフセットとぼかし。

レイヤーリスト(抜粋)

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

構造

javascript
// 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 }
      }
    }
  ]
}

レイヤーの使い方

位置とサイズは比率なので、同じリストがどのピクセルサイズでもそのまま使えます。

  1. 1使用するピクセルサイズを決めます。imageSize は解析時のサイズで、各 box はその比率です。
  2. 2Lbg をいちばん下に置き、全面を覆わせます。
  3. 3残りを並べます。parentId でまとめ、その中で paintOrder の昇順(奥から手前)に並べます。
  4. 4ui と icon の PNG をそれぞれの box に配置し、instances の各位置にも同じ画像を置きます。テキストレイヤーは text の文字列と書式を使います。
Lbg は imageSize より大きく返る場合があります。同じサイズだと決めつけず、拡大縮小してください。
テキストは画像ではなく文字列と書式で返るため、編集も翻訳もでき、どのサイズでも鮮明なままです。

配置リストの作成

javascript
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 px120
2K≤ 2048 px180
4K> 2048 px250
ティア価格は管理画面で変更できるため、その呼び出しの正確な金額は送信レスポンスの estimatedCredits を参照してください。

制限

値説明
2048 px解析前に元画像は長辺 2048 px へ縮小されます。
3001 枚あたり最大 300 要素まで検出します。
20 MBインライン base64 メディアは 1 項目 20 MB まで。
2〜3 分エンドツーエンドの標準所要時間。
7 日タスク記録とファイルの保持期間。
約 1 時間署名付きダウンロード URL の有効期間。

エラー

送信時のエラーは同期的に返ります。実行時のエラーはタスクが failed になり error オブジェクトが付きます。

ステータスコード意味
400—リクエストの形式が不正です。多くは messages[] にも referenceImage にも元画像が無いケースです。
401INVALID_API_KEY · INVALID_ORG_API_KEYAPI キーが無いか無効です。
402INSUFFICIENT_CREDITS · INSUFFICIENT_ORG_CREDITSこの画像の解像度ティアに必要なポイントが不足しています。
403API_SERVICE_NOT_ALLOWED · ORG_DISABLEDそのキーまたは組織にこのサービスの利用権限がありません。
413—インライン base64 画像が 20 MB を超えています。https URL で渡してください。
429RATE_LIMIT_MINUTE · RATE_LIMIT_DAY · CONCURRENCY_LIMIT_EXCEEDEDレートまたは同時実行の上限に達しました。少し待って再試行してください。
failederror.codeタスク開始後に実行が失敗しました。error.code と error.message に理由が入り、確保したポイントは全額返還されます。

エラーレスポンス — HTTP 400

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

失敗したタスク(ポーリング結果)

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