Для AI-агентов: markdown этой страницы — /docs/connect-media.mdиндекс документации — /llms.txt
Файлы из вашего ИИ
Обновлено
Подключите MCP по инструкции вашего приложения. Первое действие агента — get_onboarding_state с intent: auto. Дальше он использует текущую инструкцию сервера, сам выполняет разрешённые действия и спрашивает только недостающие данные. Можно продолжить тот же бизнес в вебе или Mini App.
Для тестового товара передайте полную карточку и отдельно полное сообщение цифровой доставки. Поддерживаются текст, сообщение только с медиа, фото, видео, PDF и другие допустимые документы, несколько файлов и допустимые альбомы. Фото не обязательно. Агент сохраняет подписи, форматирование и порядок файлов; подтверждает готовность и доставку серверными проверками.
Как файл попадает на платформу
Способ зависит от приложения, в котором работает агент:
| Где работает агент | Как передаются файлы |
|---|---|
| ChatGPT | Прикрепите файлы к сообщению. ChatGPT сам передаёт их в media_import_files полем files: ссылку на скачивание и file_id каждого файла. |
| Claude в вебе, десктопе или телефоне через коннектор | Вложения чата в инструмент не передаются: у них нет ссылки. Агент указывает в sources HTTPS-ссылки на файлы: на вашем сайте на платформе или на разрешённом файловом хосте. Файл вашего опубликованного сайта платформа читает прямо из его хранилища, без запроса по сети; ссылка на сайт другого бизнеса отклоняется. Если ссылки нет, загрузите файл в вебе или Mini App. |
| Claude Code, Codex, Cursor, SDK — везде, где агент читает файлы и делает HTTP-запросы | Агент вызывает media_request_upload, отправляет байты каждого файла HTTP PUT по выданному URL с точным размером и завершает загрузку через media_finalize. |
Base64 не поддерживается ни в параметрах инструментов, ни в тексте сообщения. Путь к локальному файлу и выдуманная ссылка тоже не подходят.
За один вызов можно передать до 10 файлов и ссылок вместе. Крупный файл импортируется в фоне: media_import_files отвечает COMMITTED с mediaRefs или IMPORTING с uploadId. Тогда агент проверяет media_get_status, пока не получит COMMITTED или FAILED с кодом причины. Ответ STAGING означает, что импорт не идёт: агент повторяет тот же вызов с тем же ключом idempotency_key.
Один ключ idempotency_key относится к одному набору файлов. Повтор с теми же файлами возвращает тот же результат — кроме отказов по вине источника (MEDIA_SOURCE_UNAVAILABLE, MEDIA_TRANSFER_TIMEOUT): такой повтор переносит файл заново; с другими файлами — отказ MEDIA_MANIFEST_CONFLICT (в REST — HTTP 409). Для других файлов нужен новый ключ.
Как получить файл обратно
media_get_download_link с media_ref подтверждённого файла вашего бизнеса возвращает временную ссылку на скачивание и момент expiresAt, после которого она перестаёт работать; затем агент запрашивает новую. В REST то же даёт GET /api/v1/media/download-link?media_ref=… — параметр называется так же, как поле инструмента. Ссылка не раскрывает, где файл хранится, а сам файл через инструмент не передаётся. На значение, которое не является mediaRef, ответ — VALIDATION_ERROR; на mediaRef другого бизнеса, неподтверждённый или несуществующий ответ один — MEDIA_SLOT_NOT_FOUND.
Лимиты размера зависят от тарифа, на бесплатном импорт недоступен. Отказ называет причину кодом, например MEDIA_TOO_LARGE или MEDIA_SOURCE_NOT_ALLOWED, и сообщает лимит, тариф или адрес источника без пути. Агент не должен обещать доступ, загрузку или выдачу без результата. В инструмент создания контента передаются только подтверждённые постоянные mediaRefs.
Токен собственного Telegram-бота и учётные данные платёжного провайдера можно передать агенту для авторизованного типизированного инструмента выбранного бизнеса. Агент не повторяет секреты в ответах и не помещает их в документы или страницы. Авторизация MCP-коннектора выполняется в настройках приложения.
После короткого отвлекающего вопроса агент возвращается к текущему шагу, а по просьбе остановиться прекращает работу. Завершение подтверждается отдельным действием и состоянием сервера; после него сопровождение настройки выключается.