Подключение к API

Используйте операции Make-модулей непосредственно из своего сервера, скрипта или HTTP Request в n8n. Устанавливать Make для HTTP-запросов не требуется.

1. Получите ключ и проверьте баланс

Зарегистрируйтесь на Apergrex, затем в Настройки → API создайте отдельный ключ для интеграции. Пополните баланс в кабинете или через платёжный API. Генерации и обработка списываются с баланса вашего аккаунта.

Базовый адрес:

https://apergrex.ru/franklab/api

Все пути в руководствах прибавляются к этому адресу. Например, /franklab/jobs/image даёт полный URL https://apergrex.ru/franklab/api/franklab/jobs/image: повторение franklab здесь намеренное.

read -rsp 'API key: ' FRANKLAB_KEY; echo
export FRANKLAB_KEY
export FRANKLAB_BASE_URL='https://apergrex.ru/franklab/api'
curl --fail-with-body --max-time 30 \
  -H "X-API-Key: ${FRANKLAB_KEY:?Set your API key}" \
  "$FRANKLAB_BASE_URL/v1/billing/balance"

Храните ключ в секретах серверного приложения. Не передавайте его в URL, браузерный код, логи и диалог с AI. Заголовок авторизации указан в каждом руководстве: Make-модули утилит используют Authorization: Bearer, многие генеративные маршруты — X-API-Key.

2. Выберите функцию и контракт

Название в Make помогает найти функцию, но не всегда совпадает с REST-параметром. Передавайте значения из примера конкретной операции, а не подписи выпадающего списка или выражения {{parameters.…}}. Один модуль может обращаться к нескольким маршрутам с разными форматами ответа.

3. Подготовьте входные файлы

Прямая ссылка или загрузка файла

Если операция принимает imageUrl, videoUrl или другое поле с URL, можно передать прямую публичную HTTPS-ссылку без предварительной загрузки. Ссылка из облачного хранилища должна возвращать сам файл без входа в аккаунт, cookies и заголовка авторизации. Страница общего доступа, HTML-превью, локальный путь и браузерный blob: не являются ссылками на медиафайл. Ссылка должна оставаться доступной всё время обработки; истёкшую ссылку замените перед новым запросом. Импорт, описанный ниже, отклоняет частные/локальные адреса и небезопасные перенаправления.

Локальный файл загрузите через multipart. Замените input.png своим файлом:

set -e
curl --fail-with-body --max-time 120 \
  -H "Authorization: Bearer ${FRANKLAB_KEY:?Set your API key}" \
  -F 'file=@./input.png;type=image/png' \
  "$FRANKLAB_BASE_URL/franklab/jobs/upload" \
  -o upload.json
jq -e '.success == true and (.data.storedFileId | type == "string")' upload.json >/dev/null
jq '.data | {url,storedFileId,mimeType,sizeBytes,expiresAt}' upload.json

Не задавайте Content-Type: application/json для multipart: cURL сам добавляет boundary. Ответ загрузки: {success:true,data:{url,storedFileId,mimeType,sizeBytes,expiresAt}}. Значение data.url передавайте в поля с URL; data.storedFileId — ID файла вашего аккаунта. Исходники после загрузки хранятся 7 дней. Загрузка принимает поддерживаемые изображения, видео и аудио до 150 MiB и не меняет формат; конкретная операция обработки может иметь более строгие ограничения.

Импорт ссылки или чтение метаданных загруженного файла

Некоторым полям, например Alibaba firstFrame, нужен дескриптор с ID файла и измеренными размерами. Используйте POST /franklab/jobs/import с ключом того же аккаунта. Передайте kind и ровно одно поле: url или storedFileId:

Word, Excel, PowerPoint и другие офисные документы сначала экспортируйте в PDF. Импорт определяет свойства по содержимому файла; он не перекодирует файл и не делает его подходящим для любой модели.

Импорт изображения по прямой ссылке:

set -e
jq -n --arg url 'https://media.example.com/product-front.png' \
  '{url:$url,kind:"image"}' > import-request.json
curl --fail-with-body --max-time 180 \
  -H "Authorization: Bearer ${FRANKLAB_KEY:?Set your API key}" \
  -H 'Content-Type: application/json' \
  --data-binary @import-request.json \
  "$FRANKLAB_BASE_URL/franklab/jobs/import" \
  -o imported.json
jq -e '.success == true and (.data.storedFileId | type == "string")' imported.json >/dev/null
jq '.data' imported.json

Если изображение уже загружено, импортируйте его по ID из сохранённого ответа:

set -e
jq -e '.data | {storedFileId,kind:"image"} | select(.storedFileId | type == "string" and length > 0)' \
  upload.json > import-request.json
curl --fail-with-body --max-time 180 \
  -H "Authorization: Bearer ${FRANKLAB_KEY:?Set your API key}" \
  -H 'Content-Type: application/json' \
  --data-binary @import-request.json \
  "$FRANKLAB_BASE_URL/franklab/jobs/import" \
  -o imported.json
jq -e '.success == true and (.data.storedFileId | type == "string")' imported.json >/dev/null
jq '.data' imported.json

Ответ: {success:true,data:{storedFileId,url,mimeType,sizeBytes,width?,height?,durationSeconds?,fps?,pageCount?}}. Необязательные поля возвращаются по типу файла: размеры изображения, размеры/длительность/частота кадров видео, длительность аудио или число страниц PDF. Используйте значения, измеренные API, а не предположительные размеры. Новый импортированный исходник хранится 14 дней; чтение метаданных уже загруженного файла не продлевает его исходный срок хранения. Пример Alibaba по первому кадру показывает, как собрать дескриптор из этого ответа.

Редактирование изображений Qwen

Для POST /make/alibaba/images проще всего передать editImageUrls: 1–3 прямых HTTPS-ссылки, PNG/JPEG/WebP, до 10 MiB на изображение. Лимит Qwen меньше общего лимита импорта изображений. Сервер импортирует референсы для вашего аккаунта:

{
  "model": "qwen-image-3.0",
  "operation": "image_edit",
  "prompt": "Replace the background with a pale blue studio backdrop.",
  "width": 1024,
  "height": 1024,
  "editImageUrls": ["https://media.example.com/product-front.png"]
}

Альтернатива — собрать значения data.storedFileId из ответов загрузки в editImageIds. Для одного изображения из upload.json:

jq -e '.data.storedFileId | select(type == "string" and length > 0) | {model:"qwen-image-3.0",operation:"image_edit",prompt:"Replace the background with a pale blue studio backdrop.",width:1024,height:1024,editImageIds:[.]}' \
  upload.json > qwen-request.json

Передавайте ровно одно поле: editImageUrls или editImageIds. ID файлов MOON GPT и объекты Make {value} сюда не подходят. До отправки генерации получите оценку с выбранной моделью, qwenOperation:"image_edit", imageCount, width, height и n; оценка не скачивает референсы. Полный контракт запроса и результата — в разделе Qwen.

Другие модули могут принимать прямые ссылки, иметь собственный upload API или использовать другие ID. Следуйте формату входа конкретного модуля: идентификаторы разных систем не взаимозаменяемы.

4. Оцените стоимость и создайте одну задачу

Используйте оценку именно выбранного маршрута, модели и набора параметров. Сверьте сумму с available; прайс-лист показывает базовые ставки, а не гарантированную персональную цену запроса. Где отдельная оценка отсутствует, это указано в руководстве; неизвестная стоимость не означает ноль.

Первый полный пример MARS проходит все шаги: баланс → оценка → запуск → статус → ссылка на видео. Команда создания задачи может зарезервировать деньги. Не запускайте весь каталог примеров подряд.

5. Дождитесь результата

Сохраните ID сразу после создания. Опрос выполняйте через статусный маршрут той же операции и с тем же аккаунтом. Форматы различаются:

Ограничьте число проверок и время ожидания. Сохраните ID при исчерпании ожидания и продолжайте проверять его позже. При тайм-ауте запуска, 5xx или отсутствии ID не повторяйте POST автоматически: сервер мог принять задачу. Сверьте историю и обратитесь в поддержку. Idempotency-Key платёжного API не делает произвольный маршрут генерации идемпотентным.

Успех подтверждается доступным результатом. Скачайте файл и проверьте формат; для текста проверьте содержимое ответа. Итоговое списание сверяйте по транзакциям. Оценка, резерв и окончательная стоимость могут различаться.

Python: проверка подключения

Стандартная библиотека, без дополнительных пакетов. Пример только читает баланс.

import json
import os
from urllib.request import Request, urlopen

base = "https://apergrex.ru/franklab/api"
request = Request(base + "/v1/billing/balance", headers={
    "X-API-Key": os.environ["FRANKLAB_KEY"],
})
with urlopen(request, timeout=30) as response:
    balance = json.load(response)
print({name: balance.get(name) for name in ("available", "reserved")})

Для JSON-запроса генерации задайте method="POST", data=json.dumps(payload).encode() и заголовок Content-Type: application/json. payload, путь создания и статусный путь берите из раздела выбранного модуля; не добавляйте автоматические повторы создания задачи.

JavaScript: проверка подключения

Для серверного Node.js с встроенным fetch. Пример только читает баланс.

const key = process.env.FRANKLAB_KEY;
if (!key) throw new Error("Set FRANKLAB_KEY");
const base = "https://apergrex.ru/franklab/api";
const response = await fetch(`${base}/v1/billing/balance`, {
  headers: { "X-API-Key": key },
  redirect: "error",
  signal: AbortSignal.timeout(30000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { available, reserved } = await response.json();
console.log({ available, reserved });

Для JSON-запроса генерации добавьте method: "POST", body: JSON.stringify(payload) и Content-Type: application/json. Перед следующим шагом проверьте не только HTTP-статус, но и поля успеха/ошибки конкретного контракта.

Передать документацию в AI

В каждом разделе доступны открытие, скачивание и копирование Markdown, а также передача в AI. Передавайте раздел нужного семейства вместе с этой инструкцией. Настоящий API-ключ подставляйте только в своём окружении после получения кода.