Документация по SUPA Render API

Авторизация

Для того, чтобы выполнять запросы к нашему API, у вас должен быть API-ключ, который вы можете запросить здесь.

• Для авторизации вы должны добавлять API-ключ к каждому запросу в заголовке Authorization, следующим образом:

Authorization: Bearer YOUR_API_KEY

Подготовка шаблона

Создание видео, изображений и PDF-файлов происходит на основе креатива-шаблона. Креативом-шаблоном может быть любой креатив, созданный в вашем аккаунте. Вам достаточно знать id креатива (design_id), чтобы использовать его как шаблон для рендера через API.

Для того, чтобы сделать изменяемыми те или иные объекты (например, тексты или изображения) внутри креатива-шаблона вам нужно проставить им названия с помощью показанного на изображении ниже инструмента, в настройках объекта. Заданные названия нужно использовать при рендере в объекте objects_overrides вместо <object_name>.

Запрос на рендер

Создание изображений и видео может занимать продолжительное время, поэтому выполняется в два этапа. Первым этапом выполняется запрос на рендер, а вторым этапом периодически запрашивается статус готовности до тех пор, пока рендер не завершится. Когда рендер завершился, в ответе на запрос о статусе готовности, вы получите url сгенерированного видео, изображения или pdf-файла.

Чтобы избежать множественных запросов на получение статуса, вы также можете использовать вебхуки, чтобы подписаться обновления статуса рендеринга. Для этого, при запросе на рендеринг, укажите webhook_url с адресом вашего скрипта. Более подробно про механизм работы вебхуков читайте ниже.

Отправляем запрос на render

POST https://api.supa.ru/public/v2/render

{
  "design_id": YOUR_VIDEO_OR_IMAGE_ID, // ID креатива-шаблона
  "format": "jpg", // png / pdf / mp4
  "webhook_url": "https://...", // URL куда будет отправляться информация о статусе (POST)
  "objects_overrides": {
    ...
    "<object_name>": { // название первого объекта (текстовый элемент)
      "text": "Новый текст взамен старого", // Заменяем текст в ролике
    },
    "<object2_name>": { // название второго объекта (изображение)
      "path": "https://...", // Заменяем изображение
    }
    ...
  },
}

Параметры и их описания:

Ответ в случае успеха

При отправке запроса на рендеринг, задание с идентификатором task_id ставится в очередь. Далее вы можете отслеживать статус выполнения задания через status_url, который вы получите в ответ на ваш запрос к /render.

{
  "task_id": 123456,
  "status_url": "https://api.supa.ru/public/v2/tasks/123456"
}

Максимальное количество заданий в очереди определяется условиями вашего тарифного плана. Задания выполняются по порядку (принцип FIFO) и одновременно будет рендериться только один креатив (если иное не предусмотрено вашим тарифным планом).

Возможные ошибки

Запрос на рендер может вернуть ошибку в таком виде:

{
  "error": "validation_error",
  "description": "Field \"objects_overrides.myimage.text\" not found"
}

Полный список ошибок представлен ниже:

Получение результата рендера

После того как запрос на рендеринг отправлен, можно начинать опрашивать полученный url с информацией о статусе с нужной периодичностью. Пожалуйста, не запрашивайте один и тот же url статуса чаще, чем раз в 5 секунд — это может привести к автоматическому временному ограничению доступа к API. Чтобы не опрашивать статус каждые несколько секунд, вы можете подписаться на вебхук при отправке запроса на рендеринг.

GET https://api.supa.ru/public/v2/tasks/123456

Получаем ответ

{
  "id": 123456,
  "state": "done" // queued, pending, error
  "design_id": 23452234,
  "result_url": "https://..."  // только в случае, если статус "done"
}

Если ваш запрос сформирован неверно или имеет место сбой API, то вы можете получить следующий ответ:

{
  "error": "task_not_found",
  "description": "Task #123456 not found"
}

Вебхуки

В случае изменения статуса на done или error, вебхук присылает данные методом POST, как в ответе, указанном выше. Вебхук отправляется один раз: если запрос не удался, то вебхук не повторяется.

Схема работы с использованием вебхука может быть затруднена при локальной разработке, так как ваш скрипт не будет доступен из внешнего интернета. Чтобы решить эту проблему, вы можете использовать выделенный ip-адрес для вашей машины или ПО для проброса локального порта в интернет, вроде ngrok.

Обработка ошибок рендеринга

Вы можете получить статус со значением “error” — это значит, что произошла ошибка при рендеринге.

{
  "id": 123456,
  "state": "error",
  "design_id": 23452234
}

При получении подобной ошибки повторите попытку генерации, а если это не поможет — обратитесь в поддержку.

Настройка текстов

Для того, чтобы заменить текст в креативе, вам необходимо передать новую текстовую строку в объекте objects_overrides при рендере. Также вы можете менять некоторые другие параметры:

...
"objects_overrides": {
  "mytext": { // название объекта
    "text": "Новый текст",
    "text_align": "left",
  }
}
...

Список параметров, доступных для изменения в текстовых элементах:

Стилизация текста

Для стилизации всего текста или его отдельных участков вы можете использовать сабстили, которые работают по принципу html-тегов, но выглядят немного по-другому. Например, чтобы поменять цвет у всего текста, сделать его жирным и подчеркнутым, вы можете использовать следующую конструкцию:

...
"objects_overrides": {
  "mytext": {
    "text": "<substyle bold=\"700\" color=\"#FF0000\" underline>Новый текст</substyle>"
  }
}
...

А чтобы выделить отдельный участок другим цветом, вы можете использовать следующий код:

{
  "text": "<substyle bold=\"400\" color=\"#ff0000\">Новый</substyle><substyle bold=\"400\" color=\"#000000\"> текст</substyle>"
}

Обратите внимание, что теги substyle не поддерживают вложенность, т.е. каждый участок текста должен быть обернут только в один сабстиль.

Далее представлен перечень всех возможных значений атрибутов substyle:

Ссылка внутри текста

Чтобы выделить ссылку внутри текста, используйте следующий код:

{
"text": "<substyle bold=\"400\" color=\"#000000\">Подробности смотрите </substyle><substyle bold=\"400\" color=\"#0061fe\" link=\"(url:https://supa.ru)\">здесь</substyle>"
}

Стратегии замены текста

Текст может заменяться с использованием разных стратегий, которые задаются в параметре config.text_replacement_strategy при отправке запроса на render, внутри настроек объекта.

Если стратегия замены текста не указана, то используется стратегия fit. Ниже приведен пример того, как задать другую стратегию:

...
"objects_overrides": {
  "mytext": {
    "text": "Новый текст",
    "config": {
      "text_replacement_strategy": "fixed-width",
    }
  }
}
...

В режиме fit, когда новый текст оказывается меньше области измененного текста, он выравнивается по вертикали, однако вы можете изменить это поведение следующим образом:

...
"objects_overrides": {
  "mytext": {
    "text": "Новый текст",
    "config": {
      "text_replacement_strategy": "fit",
      "text_replacement_strategy_fit_valign": "top" // center / bottom
    }
  }
}
...

Настройка изображений

Для замены изображения при рендере укажите URL нового изображения, загруженного с помощью метода, указанного в разделе «Загрузка своих изображений».

В примере показана замена изображения с названием myimage:

...
"objects_overrides": {
  "myimage": { // название объекта
    "path": "https://...", // URL нового изображения
  }
}
...

Загрузка своих изображений

Для того, чтобы заменить изображение в креативе-шаблоне, вам сначала нужно загрузить новое изображение на наш сервер. Внешние URLы на изображения использовать нельзя, вы можете использовать для замены только те изображения, которые загружены через метод, указанный ниже.

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

POST https://api.supa.ru/public/v2/upload

Изображение отправляется как multipart/form-data в поле с названием file (cм. пример на CURL)

Пример загрузки изображения через CURL

curl -F "file=@test.jpg" -H "Authorization: Bearer <Ключ API>" https://api.supa.ru/public/v2/upload

Ответ после загрузки изображения

{
  "result": "success",
  "url": "https://..."
}

в случае ошибки ответ будет таким:

{
  "result": "error",
  "reason": "Описание ошибки"
}

Стратегии замены изображения

Изображение может заменяться тремя возможными способами, которые задаются в параметре config.media_replacement_strategy. Ниже показано поведение изображения при различных значениях этого параметра:

Если стратегия замены текста не указана, то используется стратегия cover. Ниже приведен пример того, как задать другую стратегию:

...
"objects_overrides": {
  "myimage": {
    "path": "https://...", // URL нового изображения
    "config": {
      "media_replacement_strategy": "contain"
    }
  }
}
...

Настройка фигур

Вы можете программно заменять заливку и границу фигуры: давайте рассмотрим возможные варианты.

Замена заливки фигуры на изображение

Вы можете также изменить заливку фигуры на изображение, загруженное через API. Для этого сформируйте object_overrides следующим образом:

...
"objects_overrides": {
  "myshape": {
    "background": {
      "type": "image",
      "path": "https://..." // URL нового изображения
    }
  }
}
...

Система возьмёт центральную часть изображения, а остальная часть изображения будет скрыта, если соотношение сторон фигуры не совпадает с соотношением сторон изображения.

Замена заливки фигуры на сплошной цвет

...
"objects_overrides": {
  "myshape": {
    "background": {
      "type": "color",
      "color": "#ff0000" // Цвет в hex
    }
  }
}
...

Замена границы фигуры

...
"objects_overrides": {
  "myshape": {
    "border": {
      "width": 5,
      "color": "#ff0000" // Цвет в hex
      "style": "solid" // или dashed
    }
  }
}
...

Настройка диаграмм

Если в вашем креативе есть график или диаграмма, то вы можете программно менять ее значения. В параметре chart_data вы передаёте весь набор данных для диаграммы, в том же виде, как если бы вы заполняли таблицу значений в настройках объекта. Обратите внимание, что первое значение первой строки должно быть null.

...
"objects_overrides": {
  "mychart": {
    "chart_data": [
      [null, "Столбец 1", "Столбец 2", "Столбец 3"]
      ["Элемент 1", 3, 6, 3],
      ["Элемент 2", 5, 10, 6],
      ["Элемент 3", 4, 8, 5]
    ]
  }
}
...

Настройка мокапов

Мокапы состоят из слоев, поэтому для замены изображения на мокапе или замены цвета в элементах мокапа, вам нужно указать ID слоя, который показан на изображении ниже.

Пример настройки слоев мокапа:

...
"objects_overrides": {
  "mymockup": {
    "mockup_data": {
      "<layer_id>": {
        "image_url": "https://..." // id слоя мокапа с изображением
      },
      "<layer_id>": {
        "color": "#ff0000" // id слоя мокапа с настройкой цвета
      },
      "<layer_id>": {
        "hidden": true // скрыть слой
      }
    }
  }
}
...

Полный список возможных параметров для слоя мокапа:

Общие параметры

Есть параметры, которые применимы к объектам вне зависимости от их типа. В основном, они касаются местоположения, размера и других общих свойств:

...
"objects_overrides": {
  "anyobjectname": {
    "x": 34,
    "y": 234,
    "width": 325
  }
}
...

Полный список параметров:

Ограничения API

• Нельзя создавать видео длиннее 15 секунд

• Скачивание в формате анимационного GIF пока недоступно

• Максимальный размер загружаемых на сервер файлов - 10 мегабайт

• Нет возможности загружать через API видеоролики на сервер для замены имеющихся видео на холсте

• API доступно только для администратора аккаунта и недоступно для участников команды

• Запрещено выполнять более 50 запросов к API в минуту (если иное не предусмотрено вашим тарифным планом)

Правила API

• Если ваши конечные пользователи (клиенты) будут иметь доступ к инструменту созданному на основе SUPA Render API, то требуется дополнительное разрешение со стороны SUPA. При этом если возможностями SUPA Render API будете пользоваться исключительно вы или ваши сотрудники, а инструмент не будет доступен публично, то согласование не требуется. В случае нарушения данного правила, доступ к API может быть приостановлен.

• Запрещено передавать / перепродавать доступ к API третьей стороне

• Запрещено использовать функционал API, который не указан в данной документации

• Запрещено предпринимать действия, направленных на подрыв сетевой безопасности, либо нарушения работы программно-технических средств сервиса SUPA

• Запрещено использовать API в целях, нарушающих законы РФ

• Запрещено загружать в API материалы, противоречащие законам РФ