Agent API & MCP

Zielgruppe: LLM-Agenten, Tool-Calling-Runtimes und MCP-Clients (Cursor, Claude Desktop). Für menschliche Backends und Storefronts nutzen Sie /v1/* + OpenAPI .

KI-Integrationen: MCP und der Skill hiobuy-agent-api stellen LLM-Agenten Live-China sourcing-Tools auf 1688, Taobao und Weidian bereit — Stichwortsuche, Bildsuche und zweisprachige Produktdetails für shopping agent-Workflows in Cursor und Claude Desktop.

Auth: nur Live-Keys hio_live_*. Sandbox-Keys (hio_test_*) und Sandbox-Fixtures gelten nicht für /ai/v1 oder /mcp.

Siehe auch: Authentifizierung · Produkte · Antwortformat · Fehler · Ratenlimits

Welche Oberfläche wann

Tool-data-Payloads entsprechen den Standard-Formen aus Produkt-Antwortmodelle und Listen-Endpunkten — nie Rohformat upstream.

Voraussetzungen (Live-Key)

Vor Aufruf von /ai/v1 oder /mcp:

1. Im HIOBuy Developer Portal  registrieren und App anlegen; auf Freigabe warten.
2. Kanäle autorisieren (1688, Taobao, Weidian, …) — wie Portal-Autorisierung.
3. Live API Key unter API Keys erstellen (hio_live_* — nur einmal bei Erstellung sichtbar).
4. Mindest-Scopes für Phase-1-Tools vergeben:
   • product:detail — product.get_detail
   • product:search — product.search, product.upload_image, product.search_by_image

Fehlende Kanal-Auth oder Scope → 401 / 403. Live-Aufrufe verbrauchen Kanal-Kontingent und werden wie /v1 protokolliert.

Basis-URL & Authentifizierung

Gleicher Host wie Public API, z. B. https://api.hiobuy.com.

Authorization: Bearer hio_live_<your_key>

Jedes Tool mappt auf einen bestehenden API-Key-Scope — es gibt keinen separaten Scope tools:*.

HTTP-Endpunkte (/ai/v1)

Tools auflisten

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

Liefert nur Tools, die die Scopes des Keys erlauben. Jeder Eintrag enthält id, version, domain, description und JSON Schema input_schema.

Tool aufrufen

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

Erfolgs-Envelope (alle Tools):

Fehler: HTTP 4xx/5xx mit { "error": { "code", "message", "request_id" } } — kein Feld ok. Gemeinsame Codes siehe Fehler (INVALID_API_KEY, FORBIDDEN, RATE_LIMITED, …).

Phase-1-Tools (Produkte)

product.get_detail

• Kanal: taobao | 1688 | weidian
• Pflicht: channel + eines von product_id | url | mi_id | tao_password
• Optional: language (Standard en)
• data: { "product": StandardProduct }

product.search

• Pflicht: channel, keyword
• Optional: page, page_size, language, sort, price_start, price_end
• data: StandardProductList (wie Body von POST /v1/products/search)

product.upload_image

• Kanal: 1688 | taobao
• 1688: image_base64 oder image_url
• Taobao: image_base64 erforderlich
• data: { "channel", "image_id" } — image_id für paginierte Bildsuche wiederverwenden

product.search_by_image

• Kanal: 1688 | taobao (nicht Weidian)
• Eingabe: image_id | image_url | image_base64
• Empfohlener Ablauf für Pagination: einmal product.upload_image → mehrere product.search_by_image nur mit image_id

Agent-Workflow (HTTP)

1. GET /ai/v1/tools → Tool-Metadaten / input_schema cachen
2. Modell wählt tool_id + arguments aus Nutzerabsicht
3. POST /ai/v1/tools/call (Bearer hio_live_…)
4. data für den Nutzer zusammenfassen

Typische Ketten:

• Ein-Schritt-Bildsuche: product.search_by_image mit image_url oder image_base64
• Paginierte Bildsuche: product.upload_image → product.search_by_image (image_id + page)
• Nach Artikelauswahl: product.get_detail

MCP-Server (/mcp) — China sourcing für KI-Agenten

In Cursor, Claude Desktop und anderen MCP-Clients rufen Agenten Tools für China sourcing und Proxy-Shopping auf 1688 (Großhandel), Taobao (Retail) und Weidian auf — Stichwortsuche, Bild-Upload, Bildsuche, zweisprachige Produktdetails. Typische shopping agent-Ketten: Fabrikpreise auf 1688 vergleichen, Taobao-Alternativen finden, Weidian-Kataloge sichten, dann SKU/Bestand via product.get_detail prüfen.

Die gleiche Tool-Runtime ist als MCP Server über Streamable HTTP erreichbar (Cursor, Claude Desktop, andere MCP-Clients).

Auth: gleicher Header Authorization: Bearer hio_live_*.

Fähigkeiten:

• Tools — tools/list, tools/call (gleiche tool_id-Werte wie /ai/v1)
• Prompts — eingebaute Produkt-/Bildsuche-/Research-Workflows
• Resources — hiobuy://agent/*-URIs (resources/list, resources/read, Templates)
• Subscriptions — resources/subscribe → SSE notifications/resources/updated
• Streaming — GET /mcp öffnet SSE; POST mit Accept: text/event-stream kann JSON-RPC streamen
• Sampling — Server kann sampling/createMessage per SSE senden; Client antwortet via POST /mcp (202)

Empfohlener Session-Ablauf:

1. POST initialize → Antwort-Header Mcp-Session-Id speichern
2. GET /mcp mit Session → SSE-Listener öffnen
3. POST notifications/initialized
4. POST tools/list / tools/call

Bei Erfolg liefert tools/call → result.content[0].text dasselbe JSON-Envelope wie /ai/v1/tools/call.

Cursor-Konfiguration (Shopping-Agent-MCP + China sourcing 1688/Taobao/Weidian)

In Settings → MCP oder .cursor/mcp.json eintragen, damit Cursor Live-China sourcing-Tools für 1688 / Taobao / Weidian erhält:

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

hio_live_xxx durch Ihren Live-Key ersetzen. Keys serverseitig halten — nicht in öffentliche Repos committen.

Cursor Agent Skill (hiobuy-agent-api) — China shopping agent

Der optionale Cursor Agent Skill hiobuy-agent-api hilft Coding-Agenten, China sourcing-Flows auf 1688, Taobao und Weidian anzubinden — Live-Key-Scopes, /ai/v1-Envelopes, MCP-Session-Header und Ketten Suche → Bildsuche → Detail. Für REST-Storefronts auf /v1/* nutzen Sie OpenAPI.

Er vermittelt dem Modell:

• Live-Key-Voraussetzungen und Scopes für 1688 / Taobao / Weidian-Produkttools
• /ai/v1-Request/Response-Envelopes und Phase-1-Tool-Argumente
• MCP-Session-Header und Cursor-mcp.json für China shopping-Workflows
• Fehlercodes und Sourcing-Tool-Ketten (Suche → Bildsuche → Detail)

Installation aus dem öffentlichen Repo hiobuy-agent-skills  — klonen oder SKILL.md ins Cursor-Skills-Verzeichnis kopieren (siehe Cursor Agent Skills ).

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

Der Skill ergänzt diese Seite — diese Site bleibt die kanonische API-Referenz für Scopes, Kontingente und Produktfeld-Semantik.

Kurzreferenz

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}}'