Изображения через API

Сервер Senler может сам скачать изображение по ссылке, сохранить собственную копию и подготовить её для нужного ресурса. Это удобно для интеграций и агентов с MCP: не нужно открывать браузер, передавать бинарный файл через PUT и отдельно подтверждать загрузку.

Укажите источник

В JSON-запросе передайте ровно одно поле:

url: доступный серверу HTTP(S)-адрес изображения, в том числе storage_url, полученный при генерации;
attachment_id: ID готового медиа-вложения из сообщения или генерации. Нужен доступ к исходному диалогу, даже если есть права на изменение целевого ресурса.

attachment_id не равен fileId из подтверждённой загрузки. Чтобы импортировать такую загрузку в другой ресурс, используйте её возвращённый url.

Дополнительно можно передать file_name и idempotency_key. Имя не меняет формат файла: сервер проверяет его содержимое.

Выберите назначение

Все перечисленные методы используют POST. Идентификаторы в фигурных скобках замените ID нужного ресурса. Авторизация и доступные действия зависят от прав токена.

Аватары и оформление приложения применяются сразу после успешного импорта:

проект: /api/projects/{projectId}/avatar/from-url;
канал: /api/channels/{id}/avatar/from-url;
текущий пользователь: /api/cabinet/profile/avatar/from-url;
рабочий профиль агента: /api/agents/{agentId}/avatar/from-url;
только черновик агента: /api/agents/{agentId}/draft/avatar/from-url, затем нужна отдельная публикация;
автоматизация: /api/automations/{automationId}/avatar/from-url;
иконка приложения: /api/apps/{id}/icon/from-url;
обложка приложения: /api/apps/{id}/cover/from-url.

Аватар канала нельзя менять вручную у Telegram, VK, MAX и Discord: он обновляется с платформы. Для остальных типов этот метод доступен. У канала также поддерживается прежнее имя поля imageUrl; передайте только один источник: imageUrl, url или attachment_id.

Для аватара пользователя нужна сессия или пользовательский OAuth с правом can_manage_profile. Проектный API-ключ не подходит; через MCP эта операция доступна в пользовательском сервере.

Обложка приложения приводится к 706×398 пикселям. По умолчанию fit: "contain" сохраняет всю картинку с полями; fit: "cover" заполняет обложку с обрезкой краёв.

Изображения лендингов и иконки шагов нужно затем привязать к содержимому:

лендинг: /api/landings/{landingId}/assets/from-url;
лендинг агента: /api/agents/{agentId}/landing/assets/from-url;
иконка шага приложения: /api/apps/{appId}/automation-steps/icon/from-url.

Для лендинга используйте url из ответа при сохранении блока, фона, иконки или баннера. Для иконки шага передайте возвращённый key в icon_asset_key. Загрузка не сохраняет блок и не публикует лендинг или шаг.

Вложения сообщений и рассылок возвращают fileId для следующего действия:

канал: /api/dialogs/attachments/channels/{channelId}/from-url;
диалог: /api/dialogs/attachments/dialogs/{dialogId}/from-url;
тестовый черновик: /api/dialogs/attachments/projects/{projectId}/drafts/{draftId}/from-url;
автоматизация: /api/automations/{automationId}/attachments/from-url;
рассылка: /api/deliveries/attachments/from-url, с project_id в JSON.

Передайте fileId в соответствующий метод отправки сообщения или сохранения вложений шага/рассылки. Сам импорт ничего не отправляет и не запускает тест, автоматизацию или рассылку.

База знаний и документация приложения сохраняют файл в выбранную папку:

база знаний: /api/knowledge-base/files/from-url, с project_id в JSON;
документация приложения: /api/apps/{appId}/documentation/files/from-url.

Доступны folder_id, title, locale (ru или en) и image_recognition_mode. По умолчанию язык ru, а распознавание выключено: image_recognition_mode: "none". Включённое распознавание обрабатывается в базе знаний и расходует кредиты проекта; импорт сам по себе не означает, что изображение уже распознано.

Пример установки аватара

Серверный JavaScript-пример использует API-ключ или OAuth-токен. Не помещайте секретный токен в код сайта:

const response = await fetch(
  `https://api.senler.io/api/projects/${projectId}/avatar/from-url`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SENLER_API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: imageUrl,
      file_name: "project-logo",
      idempotency_key: "project-logo-v1",
    }),
  },
);
if (!response.ok) throw new Error(`Image import failed: ${response.status}`);
const result = await response.json();

projectId и imageUrl задаёт ваша интеграция. Для MCP найдите метод импорта нужного ресурса и прочитайте его параметры: например, ProjectsAvatarController_importFromUrl устанавливает аватар проекта, а AgentsAvatarController_importDraftFromUrl меняет только черновик агента. Эти методы доступны в Senler.io MCP и пользовательском MCP при соответствующих правах.

Ограничения и повтор запроса

Аватары, оформление приложения и лендинги принимают PNG, JPEG и WebP. Вложения сообщений, автоматизаций, рассылок, база знаний и документация приложения также принимают GIF. Для большинства методов предел составляет 20 МБ и 40 мегапикселей; для анимации учитываются кадры. У лендингов отдельный предел: 10 МБ и 8000 пикселей по стороне, также не более 40 мегапикселей. Лимиты хранилища проекта могут быть строже.

Для повторной отправки того же запроса используйте прежний idempotency_key с теми же параметрами. Успешный результат хранится 24 часа. Другие параметры с тем же ключом отклоняются.

Если API сообщил, что применение могло уже произойти, сначала прочитайте целевой ресурс. Не создавайте новый ключ для обхода этого конфликта: можно повторно применить уже выполненное изменение.