Agent API と MCP

対象： LLM エージェント、ツール呼び出しランタイム、MCP クライアント（Cursor、Claude Desktop）。人間向けバックエンド・ストアフロントは /v1/* + OpenAPI  を使用してください。

AI 連携： MCP と hiobuy-agent-api Skill は LLM エージェントに 1688、Taobao、Weidian のライブ China sourcing ツールを提供 — キーワード検索、画像検索、二言語商品詳細で Cursor と Claude Desktop の shopping agent ワークフローに対応。

認証： hio_live_* Live キーのみ。 サンドボックスキー（hio_test_*）と Sandbox フィクスチャ は /ai/v1 および /mcp に適用されません。

関連：認証 · 商品 · レスポンス形式 · エラー · レート制限

どのインターフェースを使うか

ツールの data ペイロードは 商品レスポンスモデル および一覧エンドポイントの標準形状と一致します — upstream 生形式はありません。

前提条件（Live キー）

/ai/v1 または /mcp を呼ぶ前に：

1. HIOBuy 開発者ポータル  で登録しアプリを作成；承認を待つ。
2. チャネル認可（1688、Taobao、Weidian など）— ポータル認可 と同様。
3. API Keys で Live API キーを作成（hio_live_* — 作成時に一度だけ表示）。
4. Phase 1 ツールに最低限のスコープを付与：
   • product:detail — product.get_detail
   • product:search — product.search、product.upload_image、product.search_by_image

チャネル未認可またはスコープ不足 → 401 / 403。Live 呼び出しはチャネルクォータを消費し、/v1 と同様にログされます。

ベース URL と認証

Public API と同じホスト、例：https://api.hiobuy.com。

Authorization: Bearer hio_live_<your_key>

各ツールは既存の API Key スコープに対応 — 別途 tools:* スコープはありません。

HTTP エンドポイント（/ai/v1）

ツール一覧

curl -s https://api.hiobuy.com/ai/v1/tools \
  -H "Authorization: Bearer hio_live_xxx"

キーのスコープで許可されたツールのみ返します。各エントリに id、version、domain、description、JSON Schema input_schema が含まれます。

ツール呼び出し

POST /ai/v1/tools/call
Authorization: Bearer hio_live_xxx
Content-Type: application/json
 
{
  "tool_id": "product.get_detail",
  "arguments": {
    "channel": "1688",
    "product_id": "554456348334",
    "language": "en"
  }
}

成功エンベロープ（全ツール）：

失敗： HTTP 4xx/5xx、{ "error": { "code", "message", "request_id" } } — ok フィールドなし。共通コードは エラー（INVALID_API_KEY、FORBIDDEN、RATE_LIMITED など）。

Phase 1 ツール（商品）

product.get_detail

• チャネル： taobao | 1688 | weidian
• 必須： channel + product_id | url | mi_id | tao_password のいずれか
• 任意： language（デフォルト en）
• data： { "product": StandardProduct }

product.search

• 必須： channel、keyword
• 任意： page、page_size、language、sort、price_start、price_end
• data： StandardProductList（POST /v1/products/search ボディと同じ）

product.upload_image

• チャネル： 1688 | taobao
• 1688： image_base64 または image_url
• Taobao： image_base64 必須
• data： { "channel", "image_id" } — ページング画像検索で image_id を再利用

product.search_by_image

• チャネル： 1688 | taobao（Weidian 不可）
• 入力： image_id | image_url | image_base64
• ページング推奨フロー： 一度 product.upload_image → image_id のみで複数回 product.search_by_image

エージェントワークフロー（HTTP）

1. GET /ai/v1/tools → ツールメタデータ / input_schema をキャッシュ
2. モデルがユーザー意図から tool_id + arguments を選択
3. POST /ai/v1/tools/call（Bearer hio_live_…）
4. ユーザー向けに data を要約

典型的なチェーン：

• ワンショット画像検索： image_url または image_base64 で product.search_by_image
• ページング画像検索： product.upload_image → product.search_by_image（image_id + page）
• ユーザーが商品選択後： product.get_detail

MCP サーバー（/mcp）— AI エージェント向け China sourcing

Cursor、Claude Desktop などの MCP クライアントで、エージェントは 1688（卸）、Taobao（小売）、Weidian の China sourcing・代行購入 ツールを呼び出します — キーワード検索、画像アップロード・画像検索、二言語商品詳細。典型的な shopping agent チェーン：1688 で工場見積比較、Taobao 代替品、Weidian カタログ閲覧の後、product.get_detail で SKU/在庫を確認。

同じツールランタイムが Streamable HTTP 経由の MCP Server として公開されます（Cursor、Claude Desktop、その他 MCP クライアント）。

認証： 同じ Authorization: Bearer hio_live_* ヘッダー。

機能：

• Tools — tools/list、tools/call（/ai/v1 と同じ tool_id 値）
• Prompts — 組み込み商品検索 / 画像検索 / リサーチワークフロー
• Resources — hiobuy://agent/* URI（resources/list、resources/read、テンプレート）
• Subscriptions — resources/subscribe → SSE notifications/resources/updated
• Streaming — GET /mcp で SSE 開始；Accept: text/event-stream の POST で JSON-RPC ストリーム可能
• Sampling — サーバーが SSE で sampling/createMessage を送信；クライアントは POST /mcp（202）で応答

推奨セッションフロー：

1. POST initialize → レスポンスヘッダー Mcp-Session-Id を保存
2. セッション付き GET /mcp → SSE リスナーを開く
3. POST notifications/initialized
4. POST tools/list / tools/call

成功時、tools/call → result.content[0].text は /ai/v1/tools/call と同じ JSON エンベロープです。

Cursor 設定（shopping agent MCP + 1688/Taobao/Weidian China sourcing）

Settings → MCP または .cursor/mcp.json に追加し、Cursor に 1688 / Taobao / Weidian のライブ China sourcing ツールを渡します：

{
  "mcpServers": {
    "hiobuy": {
      "url": "https://api.hiobuy.com/mcp",
      "headers": {
        "Authorization": "Bearer hio_live_xxx"
      }
    }
  }
}

hio_live_xxx を Live キーに置換。キーはサーバー側に保持 — 公開リポジトリにコミットしないでください。

Cursor Agent Skill（hiobuy-agent-api）— China shopping agent

任意の Cursor Agent Skill hiobuy-agent-api はコーディングエージェントが 1688、Taobao、Weidian の China sourcing フローを接続するのを支援 — Live キースコープ、/ai/v1 エンベロープ、MCP セッションヘッダー、検索 → 画像検索 → 詳細のチェーン。/v1/* の REST ストアフロントには OpenAPI を使用。

モデルに以下を教えます：

• 1688 / Taobao / Weidian 商品ツール向け Live キー前提とスコープ
• /ai/v1 リクエスト/レスポンスエンベロープと Phase 1 ツール引数
• China shopping ワークフロー向け MCP セッションヘッダーと Cursor mcp.json
• エラーコードと sourcing ツールチェーン（検索 → 画像検索 → 詳細）

公開リポジトリ hiobuy-agent-skills  からインストール — クローンするか SKILL.md を Cursor の skills パスにコピー（Cursor Agent Skills  参照）。

git clone https://github.com/hubinjie/hiobuy-agent-skills.git

Skill は本ページを補完します — スコープ、クォータ、商品フィールド意味については本サイトが正規 API リファレンスです。

クイックリファレンス

BASE=https://api.hiobuy.com
KEY=hio_live_xxx
 
curl -s "$BASE/ai/v1/tools" -H "Authorization: Bearer $KEY"
 
curl -s "$BASE/ai/v1/tools/call" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool_id":"product.search","arguments":{"channel":"1688","keyword":"phone case","page":1,"page_size":5}}'