Agent API et MCP

Public : agents LLM, runtimes d’appel d’outils et clients MCP (Cursor, Claude Desktop). Pour les backends humains et vitrines, utilisez /v1/* + OpenAPI .

Intégrations IA : MCP et le Skill hiobuy-agent-api exposent aux agents LLM des outils China sourcing en direct sur 1688, Taobao et Weidian — recherche par mot-clé, recherche par image et détail produit bilingue pour les workflows shopping agent dans Cursor et Claude Desktop.

Auth : clés Live hio_live_* uniquement. Les clés sandbox (hio_test_*) et les fixtures Sandbox ne s’appliquent pas à /ai/v1 ni /mcp.

Voir aussi : Authentification · Produits · Format de réponse · Erreurs · Limites de débit

Quelle surface utiliser

Les charges data des tools correspondent aux formes standard des modèles de réponse produit et des endpoints de liste — jamais au format brut upstream.

Prérequis (clé Live)

Avant d’appeler /ai/v1 ou /mcp :

1. Inscrivez-vous et créez une app dans le portail développeur HIOBuy  ; attendez l’approbation.
2. Autorisez les canaux (1688, Taobao, Weidian, …) — comme l’autorisation portail.
3. Créez une clé API Live sous API Keys (hio_live_* — affichée une seule fois à la création).
4. Accordez les scopes minimum pour les tools Phase 1 :
   • product:detail — product.get_detail
   • product:search — product.search, product.upload_image, product.search_by_image

Canal non autorisé ou scope manquant → 401 / 403. Les appels Live consomment le quota canal et sont journalisés comme /v1.

URL de base et authentification

Même hôte que l’API publique, ex. https://api.hiobuy.com.

Authorization: Bearer hio_live_<your_key>

Chaque tool correspond à un scope API Key existant — il n’y a pas de scope séparé tools:*.

Points de terminaison HTTP (/ai/v1)

Lister les tools

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

Ne renvoie que les tools autorisés par les scopes de la clé. Chaque entrée inclut id, version, domain, description et le JSON Schema input_schema.

Appeler un tool

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

Enveloppe de succès (tous les tools) :

Échec : HTTP 4xx/5xx avec { "error": { "code", "message", "request_id" } } — pas de champ ok. Voir Erreurs pour les codes partagés (INVALID_API_KEY, FORBIDDEN, RATE_LIMITED, …).

Tools Phase 1 (produits)

product.get_detail

• Canal : taobao | 1688 | weidian
• Requis : channel + l’un de product_id | url | mi_id | tao_password
• Optionnel : language (défaut en)
• data : { "product": StandardProduct }

product.search

• Requis : channel, keyword
• Optionnel : page, page_size, language, sort, price_start, price_end
• data : StandardProductList (identique au corps de POST /v1/products/search)

product.upload_image

• Canal : 1688 | taobao
• 1688 : image_base64 ou image_url
• Taobao : image_base64 requis
• data : { "channel", "image_id" } — réutilisez image_id pour la recherche par image paginée

product.search_by_image

• Canal : 1688 | taobao (pas Weidian)
• Entrée : image_id | image_url | image_base64
• Flux recommandé pour la pagination : product.upload_image une fois → plusieurs appels product.search_by_image avec image_id uniquement

Flux agent (HTTP)

1. GET /ai/v1/tools → mettre en cache métadonnées tools / input_schema
2. Le modèle choisit tool_id + arguments selon l'intention utilisateur
3. POST /ai/v1/tools/call (Bearer hio_live_…)
4. Résumer data pour l'utilisateur

Chaînes typiques :

• Recherche image en une étape : product.search_by_image avec image_url ou image_base64
• Recherche image paginée : product.upload_image → product.search_by_image (image_id + page)
• Après choix d’un article : product.get_detail

Serveur MCP (/mcp) — China sourcing pour agents IA

Dans Cursor, Claude Desktop et autres clients MCP, les agents appellent des outils pour China sourcing et proxy shopping sur 1688 (gros), Taobao (retail) et Weidian — recherche par mot-clé, upload et recherche par image, détail produit bilingue. Chaînes shopping agent typiques : comparer les devis usine sur 1688, trouver des alternatives Taobao, parcourir les catalogues Weidian, puis approfondir SKU/stock via product.get_detail.

Le même runtime d’outils est exposé en MCP Server via Streamable HTTP (Cursor, Claude Desktop, autres clients MCP).

Auth : même en-tête Authorization: Bearer hio_live_*.

Capacités :

• Tools — tools/list, tools/call (mêmes valeurs tool_id que /ai/v1)
• Prompts — workflows intégrés recherche produit / image / veille
• Resources — URI hiobuy://agent/* (resources/list, resources/read, modèles)
• Subscriptions — resources/subscribe → SSE notifications/resources/updated
• Streaming — GET /mcp ouvre SSE ; POST avec Accept: text/event-stream peut streamer JSON-RPC
• Sampling — le serveur peut envoyer sampling/createMessage via SSE ; le client répond via POST /mcp (202)

Flux de session recommandé :

1. POST initialize → conserver l’en-tête de réponse Mcp-Session-Id
2. GET /mcp avec session → ouvrir l’écouteur SSE
3. POST notifications/initialized
4. POST tools/list / tools/call

En cas de succès, tools/call → result.content[0].text est la même enveloppe JSON que /ai/v1/tools/call.

Configuration Cursor (MCP shopping agent + China sourcing 1688/Taobao/Weidian)

Ajoutez dans Settings → MCP ou .cursor/mcp.json pour donner à Cursor des outils China sourcing en direct sur 1688 / Taobao / Weidian :

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

Remplacez hio_live_xxx par votre clé Live. Gardez les clés côté serveur — ne les commitez pas dans des dépôts publics.

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

Le Cursor Agent Skill optionnel hiobuy-agent-api aide les agents de codage à brancher les flux China sourcing sur 1688, Taobao et Weidian — scopes Live, enveloppes /ai/v1, en-têtes de session MCP et chaînes recherche → recherche image → détail. Pour les vitrines REST sur /v1/*, utilisez OpenAPI.

Il enseigne au modèle :

• les prérequis et scopes des clés Live pour les outils 1688 / Taobao / Weidian
• les enveloppes requête/réponse /ai/v1 et les arguments des tools Phase 1
• les en-têtes de session MCP et le câblage Cursor mcp.json pour les workflows China shopping
• les codes d’erreur et les chaînes sourcing (recherche → recherche image → détail)

Installez depuis le dépôt public hiobuy-agent-skills  — clonez ou copiez SKILL.md dans votre répertoire skills Cursor (voir Cursor Agent Skills ).

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

Le skill complète cette page — ce site reste la référence API canonique pour scopes, quotas et sémantique des champs produit.

Référence rapide

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