Realistic Icon
開発者向け

3DアイコンAPIで開発する。

フォトリアルな3Dアイコンを生成し、カタログ全体を検索し、スタジオを自社プロダクトに組み込めます。サーバーには REST、AIエージェントには MCP、非同期処理には Webhook — ひとつのプラットフォームに3つの接続口。

ロードマップの先行公開です。 このページは計画中の REST API と Webhook について説明したもので、まだ稼働しておらず、api.bluweo.com は応答しません。現在利用できるのは MCP サーバーです。 MCP ガイドを読む →

概要

3つの接続口、ひとつのプラットフォーム。

Bluweo API は、スタジオのウェブUIでできることをすべてサードパーティのアプリやAIエージェントからプログラムで扱えるようにします。3Dアイコンライブラリの検索、プロンプトからの新規バリエーション生成、ダウンロード管理、非同期イベントの購読まで対応します。

  • REST API — あらゆる HTTP クライアント向けの同期呼び出し。
  • MCP server — Claude・Cursor をはじめ MCP 対応エージェントにそのまま挿せるツール。
  • Webhooks — 時間のかかる生成処理と課金イベントの非同期プッシュ。

ご注意： API の利用は Studio プラン. に含まれます。Free と Designer プランはウェブUIのみです。下のレート制限をご覧ください。

REST・MCP・Webhook — Bluweo プラットフォームから広がる3つの接続口。

クイックスタート

60秒以内に最初のリクエストを。

  1. アカウントを作成 して Studio にアップグレードします。
  2. APIキーを発行します： /dashboard/billing → API keys. キーの先頭は blu_live_.
  3. すべてのリクエストで Bearer トークンとして送信します。
  4. 次を呼び出して GET /v1/icons/search?q=fox キーが有効か確認します。

ベースURL： https://api.bluweo.com. すべてのリクエストは HTTPS が必須です。平文の HTTP は拒否されます。

# 1. Search the icon catalogue
curl https://api.bluweo.com/v1/icons/search?q=fox \
  -H "Authorization: Bearer blu_live_..."

認証

Bearer キー、ワークスペース単位。

すべての API リクエストには Authorization: Bearer <key> ヘッダーが必要です。キーはダッシュボードから発行され、ひとつのワークスペースに紐づきます。レート制限はキーのプランで決まります。

  • キーの形式： blu_live_* (本番) または blu_test_* (サンドボックス — 課金なし、出力にウォーターマーク).
  • 表示は1回のみ： キーはサーバー側でハッシュ化して保管します。紛失した場合はローテーションしてください。
  • ローテーション： キーは次で更新できます： POST /v1/keys/:id/roll; 移行しやすいよう、古いキーは24時間だけ有効なままです。
  • 失効： DELETE /v1/keys/:id 即座に反映されます。
APIキー認証 — すべての呼び出しに Bearer ヘッダーを付与。

REST API

検索・生成・ダウンロード・管理。

すべてのエンドポイントは次の配下にあります： /v1/. JSON で送り、JSON で受け取ります。フィールドはスネークケース、タイムスタンプは UTC の ISO-8601 です。

メソッドパス用途
GET/v1/iconsアイコン一覧。タグ・スタイル・カラーで絞り込み。
GET/v1/icons/searchカタログの全文検索。
GET/v1/icons/:idアイコン単体の詳細とバリエーション。
POST/v1/icons/generateAI生成を開始。202 を返します。
GET/v1/generations/:id生成の状態・出力をポーリング。
POST/v1/icons/:id/variants既存アイコンからスタイル／カラーのバリエーションを作成。
GET/v1/collections厳選コレクションの一覧。
POST/v1/downloadsダウンロードを記録（1クレジット消費）。
GET/v1/meワークスペース情報とクレジット残高。
POST/v1/keys新しいAPIキーを発行。
DELETE/v1/keys/:idキーを失効。

生成処理は 非同期 です。POST はジョブIDとともに 202 を返し、実際のレンダリングには5〜30秒かかります。ブロックせずに、次をポーリングするか /v1/generations/:id または次を購読してください： generation.completed Webhook をご利用ください。

非同期生成のフロー — POST でキューに入り、ワーカーが処理し、Webhook が通知。
# Generate a 3D icon
curl https://api.bluweo.com/v1/icons/generate \
  -X POST \
  -H "Authorization: Bearer blu_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "cute 3D fox character, studio lighting",
    "kind": "icon",
    "aspect": "1:1",
    "outputs": 4
  }'

# → 202 { "id": "gen_01H...", "status": "queued" }

# Poll until done
curl https://api.bluweo.com/v1/generations/gen_01H... \
  -H "Authorization: Bearer blu_live_..."

MCP サーバー

AIエージェントに Bluweo をツールとして使わせる。

Model Context Protocol （MCP）は、AIエージェントが外部ツールを呼び出すための Anthropic のオープン標準です。当社のサーバーは次でホストしています： /api/mcp （Streamable HTTP）。このURLを Claude Code・Claude Desktop・Cursor など MCP 対応クライアントに追加すれば、会話の途中でエージェントがアイコンを検索・プレビュー・ダウンロード・生成できます。インストールは不要です。

MCP サーバーは7つのツールを公開しています：

  • search_icons — キーワード／カテゴリ／スタイル／コレクションで検索。
  • get_icon — 詳細と、エージェントが見られる128pxのプレビュー。
  • list_collections — 厳選バンドルを閲覧。
  • get_account — プラン・クレジット・ダウンロード上限。
  • download_icon — 512px／オリジナルのファイル。課金はサイトと同じです。
  • generate_icon — プロンプトからスタジオで生成。
  • list_generations — 最近のスタジオ実行と画像URL。

search_icons はキーなしで使えます（1 日 100 回まで）。その他のツールには Studio プランの個人 API キーが必要です。次のヘッダーで送ります： Authorization: Bearer blu_live_… — 設定 → APIキー で作成できます。 MCP ガイドを読む →

MCP のフロー — エージェントがツールを呼び、MCP サーバーが REST に変換し、結果がエージェントに戻る。
# Claude Code — the Studio-plan key is required
claude mcp add --transport http realisticicon \
  https://realisticicon.com/api/mcp \
  --header "Authorization: Bearer blu_live_..."

Webhook

非同期処理のプッシュ通知。

ダッシュボードで Webhook の URL を設定してください。注目すべきことが起きるたび、署名付きの JSON を POST します。主な目的は、生成状態をポーリングせずに済むようにすることです。

配信するイベント：

  • generation.completed — 出力のダウンロード準備が整いました。
  • generation.failed — クレジットは自動返還されます。ペイロードにエラー理由が含まれます。
  • credits.low — 残高がプラン付与分の20%を下回りました。
  • subscription.updated — プランの変更・更新・解約。

すべてのペイロードには次のヘッダーが含まれます： Bluweo-Signature 本文を Webhook シークレットで HMAC-SHA256 したものです。 信頼する前に必ず検証してください; 署名のない POST は偽装リクエストの可能性があります。

# Example payload Bluweo POSTs to your endpoint
{
  "event": "generation.completed",
  "data": {
    "id": "gen_01H...",
    "status": "done",
    "outputs": [
      { "url": "https://cdn.bluweo.com/g/.../0.png", "width": 1024, "height": 1024 }
    ],
    "credits_used": 5
  },
  "created_at": "2026-05-16T17:42:11Z"
}

# Header attached:
# Bluweo-Signature: t=1715882531,v1=<hmac>

レート制限とクォータ

キー単位・月単位、そして公平性のため秒単位でも。

すべてのキーに2種類の制限が適用されます： 月間の総量 （プラン別クォータ）と 短時間のバースト （共有リソース保護のため 10 req/s）です。いずれも、すべてのレスポンスで標準の X-RateLimit-* ヘッダーとして返されます。

プランAPIアクセス月間クォータバースト
Free—（ウェブUIのみ）——
Designer—（ウェブUIのみ）——
StudioREST · MCP · Webhooks10,000 req10 req/s

生成とダウンロードは さらに プランのクレジットも消費します。詳しくは 料金プラン. クレジットパックの追加購入では API のクォータは増えません。生成コストを賄うだけです。

制限を超えると次が返ります： 429 Too Many Requests あわせて次のヘッダーが付きます： Retry-After その時間だけ通信を止めて再試行してください。待てばペナルティはありません。

プラン別のAPIアクセス — Free と Designer はウェブUIのみ、Studio で API が使えます。
# Every response includes:
X-RateLimit-Limit:        10000
X-RateLimit-Remaining:    9847
X-RateLimit-Reset:        1715958000   # unix epoch
X-RateLimit-Burst-Limit:  10
X-RateLimit-Burst-Remaining: 7

# On 429:
Retry-After: 3            # seconds

エラー

一般的な HTTP ステータスコードと、構造化された JSON ボディ。

よく使うステータスコード：

コード意味
200OK — 同期処理が成功。
202Accepted — 非同期ジョブをキューに登録。
400リクエストボディまたはクエリパラメータが不正。
401APIキーが未指定または不正。
402クレジット不足 — 追加購入して再試行してください。
403キーは有効ですが、プランに API アクセスが含まれていません。
404リソースが見つかりません。
409状態の競合（例：失効済みのキーをもう一度失効させた）。
429レート制限に達しました。次をご覧ください： Retry-After.
5xx当社側の問題です。冪等なリクエストは自動で再試行します。ご自身で再試行しても安全です。

エラーボディはすべて JSON です： { "error": { "code", "message", "request_id" } }. お問い合わせの際は次を添えてください： request_id トレースを追跡できます。

# 402 — out of credits
{
  "error": {
    "code": "insufficient_credits",
    "message": "Account has 3 credits; generate(outputs=4) requires 20.",
    "request_id": "req_01H9R..."
  }
}

# 429 — rate limit
{
  "error": {
    "code": "rate_limited",
    "message": "Burst limit of 10 req/s exceeded.",
    "request_id": "req_01H9R..."
  }
}

制限事項

現時点で API にできないこと — 先にお伝えしておきます。

  • オフライン／オンプレミスには非対応。 生成は常に当社のインフラ上で実行されます。アイコンライブラリはクライアント側にキャッシュできますが、AI生成はできません。
  • 1回の呼び出しでのバッチ生成には非対応。 1回の POST /v1/icons/generate で扱えるのはプロンプト1件×最大4出力です。より大きなバッチはご自身で並列化してください。バースト制限は引き続き適用されます。
  • プロンプトの最大長：1,000文字。 これを超えるプロンプトは 400 で拒否されます。
  • コンテンツポリシー。 実在の人物、著作権のあるキャラクター、性的表現、憎悪的な内容を求めるプロンプトはブロックします。その場合は 400 と次を返します： code: "policy_violation".
  • 出力解像度の上限は 2048 × 2048。 それ以上の解像度は個別契約が必要です。
  • 生成にかかる時間：5〜30秒。 最悪の場合（キューが混雑時）は最大2分です。非同期を前提に設計し、短い間隔のポーリングではなく Webhook をご利用ください。
  • MCP のトランスポート：Streamable HTTP のみ。 ローカル用の stdio（npx）パッケージはまだありません — ホストされた URL に接続してください。
  • Studio プランに SLA はありません。 Enterprise 契約には稼働率99.9%と専任サポートが含まれます。 お問い合わせ.

このリストで足りないものがありますか？

Enterprise プランで使えるようになるもの：

  • 解像度のカスタマイズと、自社ブランド素材によるスタイルのファインチューニング。
  • 専有キャパシティ（共有キューなし）。
  • VPC／オンプレミスへのデプロイ。
  • 専任サポートと99.9%のSLA。
  • 月間1万リクエストを超える場合のボリューム価格。

営業に相談する →

バージョニング

v1 が最新です。互換性を壊す変更は次として公開します： v2.

バージョンは URL のパスに含まれます： /v1/.... 同じバージョン内では 追加のみ の変更にとどめます — 新しいフィールド、新しいエンドポイント、新しいイベント種別です。バージョン内でフィールドを削除したり型を変えたりすることはありません。

次を公開したとき v2, v1 は少なくとも次の期間、稼働し続けます： 12か月 廃止予定日は次のエンドポイントで告知し、 changelog あわせて API 利用者全員にメールでお知らせします。

  • 変更履歴： GET /v1/changelog 公開以降のすべての変更を、新しい順に返します。
  • ステータスページ： status.bluweo.com 稼働状況と障害履歴をリアルタイムで確認できます。
  • メールでの更新通知： ダッシュボードから登録できます。送信するのは互換性を壊す変更の予告と重大な障害のみです。
# Read the changelog (no auth needed)
curl https://api.bluweo.com/v1/changelog | jq

# Sample entry:
{
  "version": "1.4.0",
  "released_at": "2026-04-22",
  "title": "MCP tools: list_collections + variant generation",
  "highlights": [
    "New MCP tool: list_collections",
    "Variant generation now supports color hex shorthand",
    "Webhook signatures use t=...,v1=... format (v0 deprecated 2026-10-22)"
  ]
}

開発をはじめますか？

ダッシュボードから最初のAPIキーを発行してください。個別契約が必要な場合はご相談ください。

Studio にアップグレード営業に相談する