<!-- /docs/integration (ru) -->

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

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

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

[Зарегистрируйтесь на Apergrex](https://apergrex.ru/), затем в **Настройки → API** создайте отдельный ключ для интеграции. Пополните баланс в кабинете или через [платёжный API](/docs/billing). Генерации и обработка списываются с баланса вашего аккаунта.

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

```text
https://apergrex.ru/franklab/api
```

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

```bash
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. Выберите функцию и контракт

| Что нужно сделать | Раздел | Модули |
|---|---|---|
| Создать или изменить видео | [Генерация видео](/docs/video-api) | Alibaba Video, HEYGEN AGENT, MARS, MOON, MiniMax, OMNI, SATURN, VECTOR, VENUS, X |
| Создать изображение, текст, речь или музыку; подготовить элементы | [Изображения, текст и аудио](/docs/creative-api) | Alibaba Image, JUPITER, KUSOK, MOON GPT, ORKESTR, VOLNA |
| Обработать файлы, смонтировать, добавить субтитры, выполнить SEO-аудит | [Утилиты и монтаж](/docs/utilities-api) | C2PA, FORSAJ, HOLST, INDEXLIFT, KLEY, OVERLAY, PLASTINKA, SPEKTR, SUFLER |

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

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

Если выбранная операция принимает URL, он должен быть доступен серверу. Локальный путь `/Users/…/video.mp4` и браузерный `blob:` не подходят. Требования к типу файла, размеру и длительности зависят от операции.

Для утилит с входным медиа можно загрузить файл через партнёрский маршрут:

```bash
curl --fail-with-body --max-time 120 -X POST \
  -H "Authorization: Bearer ${FRANKLAB_KEY:?Set your API key}" \
  -F 'file=@./input.mp4' \
  "$FRANKLAB_BASE_URL/franklab/jobs/upload" \
  -o upload.json
jq -er '.data.url' upload.json
```

Не задавайте `Content-Type: application/json` для этого multipart-запроса: cURL сам добавит корректный boundary. Передайте `data.url` в поле выбранной операции, например `videoUrl` или `imageUrl`. Маршруты с собственным upload/file API описаны отдельно: идентификатор файла одной системы не равнозначен URL или идентификатору другой.

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

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

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

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

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

| Семейство | Идентификатор и результат |
|---|---|
| MARS text2video | `data.task_id`, `data.task_status`; успешный результат — `data.task_result.videos[0].url` |
| Make jobs facade | `data.taskId`, `data.status`; результат — `data.result.downloadUrl` |
| Другие функции | Смотрите контракт модуля: синхронный ответ, отдельная задача или иной формат результата |

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

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

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

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

```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`. Пример только читает баланс.

```javascript
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-ключ подставляйте только в своём окружении после получения кода.