Agent API и MCP

Аудитория: LLM-агенты, среды вызова инструментов и MCP-клиенты (Cursor, Claude Desktop). Для человеческих бэкендов и витрин используйте /v1/* + OpenAPI .

Интеграции ИИ: MCP и Skill hiobuy-agent-api предоставляют LLM-агентам инструменты China sourcing на 1688, Taobao и Weidian в реальном времени — поиск по ключевым словам, поиск по изображению и двуязычные детали товара для shopping agent в Cursor и Claude Desktop.

Аутентификация: только Live-ключи hio_live_*. Песочничные ключи (hio_test_*) и фикстуры Sandbox не применяются к /ai/v1 и /mcp.

См. также: Аутентификация · Товары · Формат ответа · Ошибки · Лимиты запросов

Какой интерфейс выбрать

Полезная нагрузка data инструментов соответствует стандартным формам из моделей ответа товаров и эндпоинтов списков — никогда сырому upstream-формату.

Предварительные условия (Live-ключ)

Перед вызовом /ai/v1 или /mcp:

1. Зарегистрируйтесь и создайте приложение в портале разработчиков HIOBuy ; дождитесь одобрения.
2. Авторизуйте каналы (1688, Taobao, Weidian, …) — как при авторизации в портале.
3. Создайте Live API key в разделе API Keys (hio_live_* — показывается один раз при создании).
4. Выдайте scope минимум для инструментов Phase 1:
   • product:detail — product.get_detail
   • product:search — product.search, product.upload_image, product.search_by_image

Отсутствие авторизации канала или scope → 401 / 403. Live-вызовы расходуют квоту канала и логируются как /v1.

Базовый URL и аутентификация

Тот же хост, что и у Public API, например https://api.hiobuy.com.

Authorization: Bearer hio_live_<your_key>

Каждый tool сопоставлен существующему scope API Key — отдельного scope tools:* нет.

HTTP-эндпоинты (/ai/v1)

Список tools

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

Возвращает только tools, разрешённые scope ключа. Каждая запись включает id, version, domain, description и JSON Schema input_schema.

Вызов 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"
  }
}

Успешная обёртка (все tools):

Ошибка: 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 → несколько вызовов product.search_by_image только с image_id

Рабочий процесс агента (HTTP)

1. GET /ai/v1/tools → кэш метаданных tools / input_schema
2. Модель выбирает tool_id + arguments по намерению пользователя
3. POST /ai/v1/tools/call (Bearer hio_live_…)
4. Кратко изложить data для пользователя

Типичные цепочки:

• Поиск по изображению за один шаг: product.search_by_image с image_url или image_base64
• Постраничный поиск по изображению: product.upload_image → product.search_by_image (image_id + page)
• После выбора товара пользователем: product.get_detail

MCP-сервер (/mcp) — China sourcing для AI-агентов

В Cursor, Claude Desktop и других MCP-клиентах агенты вызывают инструменты China sourcing и proxy shopping на 1688 (опт), Taobao (розница) и Weidian — поиск по ключевым словам, загрузка и поиск по изображению, двуязычные детали товара. Типичные цепочки shopping agent: сравнить заводские цены на 1688, найти аналоги на Taobao, просмотреть каталоги Weidian, затем углубиться в SKU/остатки через product.get_detail.

Тот же runtime инструментов доступен как MCP Server через Streamable HTTP (Cursor, Claude Desktop и другие MCP-клиенты).

Аутентификация: тот же заголовок Authorization: Bearer hio_live_*.

Возможности:

• Tools — tools/list, tools/call (те же значения tool_id, что и /ai/v1)
• Prompts — встроенные сценарии поиска товаров / по изображению / исследования
• Resources — URI hiobuy://agent/* (resources/list, resources/read, шаблоны)
• Subscriptions — resources/subscribe → SSE notifications/resources/updated
• Streaming — GET /mcp открывает SSE; POST с Accept: text/event-stream может стримить JSON-RPC
• Sampling — сервер может отправить sampling/createMessage по SSE; клиент отвечает через 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 — та же JSON-обёртка, что и /ai/v1/tools/call.

Настройка Cursor (shopping agent MCP + China sourcing 1688/Taobao/Weidian)

Добавьте в Settings → MCP или .cursor/mcp.json, чтобы дать Cursor живые инструменты China sourcing для 1688 / Taobao / Weidian:

{
  "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 помогает coding-агентам подключать China sourcing на 1688, Taobao и Weidian — scope Live-ключей, обёртки /ai/v1, заголовки сессии MCP и цепочки поиск → поиск по изображению → детали. Для REST-витрин на /v1/* используйте OpenAPI.

Он обучает модель:

• предварительным условиям Live-ключа и scope для инструментов 1688 / Taobao / Weidian
• обёрткам запроса/ответа /ai/v1 и аргументам инструментов Phase 1
• заголовкам сессии MCP и настройке Cursor mcp.json для China shopping-сценариев
• кодам ошибок и цепочкам sourcing (поиск → поиск по изображению → детали)

Установите из публичного репозитория hiobuy-agent-skills  — клонируйте или скопируйте SKILL.md в каталог skills Cursor (см. Cursor Agent Skills ).

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

Skill дополняет эту страницу — этот сайт остаётся канонической справкой API по scope, квотам и семантике полей товаров.

Краткая справка

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