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

# Connect to the API

Use Make module operations directly from your server, script, or an n8n HTTP Request node. Make is not required to send HTTP requests.

## 1. Get a key and check your balance

[Register with Apergrex](https://apergrex.ru/), then create a dedicated integration key in **Settings → API**. Top up in the cabinet or through the [payment API](/en/docs/billing). Generation and processing use your account balance.

Base URL:

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

Append guide paths to this base. For example, `/franklab/jobs/image` becomes `https://apergrex.ru/franklab/api/franklab/jobs/image`: the repeated `franklab` is intentional.

```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"
```

Keep the key in server-side secrets. Never put it in URLs, browser code, logs, or AI conversations. Each guide specifies the authentication header: utility Make modules use `Authorization: Bearer`; many generation routes use `X-API-Key`.

## 2. Choose an operation and its contract

| Task | Guide | Modules |
|---|---|---|
| Generate or edit video | [Video generation](/en/docs/video-api) | Alibaba Video, HEYGEN AGENT, MARS, MOON, MiniMax, OMNI, SATURN, VECTOR, VENUS, X |
| Generate images, text, speech or music; prepare elements | [Images, text and audio](/en/docs/creative-api) | Alibaba Image, JUPITER, KUSOK, MOON GPT, ORKESTR, VOLNA |
| Process files, edit media, add subtitles or audit SEO | [Utilities and montage](/en/docs/utilities-api) | C2PA, FORSAJ, HOLST, INDEXLIFT, KLEY, OVERLAY, PLASTINKA, SPEKTR, SUFLER |

A Make label helps you find an operation, but is not necessarily a REST parameter. Use the values in the operation example, not dropdown labels or `{{parameters.…}}` expressions. One module may call multiple routes with different response shapes.

## 3. Prepare input files

If the operation takes a URL, the server must be able to access it. A local `/Users/…/video.mp4` path or browser `blob:` URL is not suitable. File type, size and duration requirements depend on the operation.

For utilities that accept media input, upload a file using the partner route:

```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
```

Do not set `Content-Type: application/json` for this multipart request: cURL adds the correct boundary. Pass `data.url` into the operation field, such as `videoUrl` or `imageUrl`. Routes with their own upload/file API are documented separately: one system's file ID is not interchangeable with another system's URL or ID.

## 4. Estimate the cost and create one task

Use the estimate for the exact route, model and parameters. Compare it with `available`; the [price list](/en/docs/pricing) contains base rates, not a guaranteed personal quote. The operation guide notes when a separate estimator is absent; an unknown cost does not mean zero.

The [complete MARS example](/en/docs) covers balance → estimate → submit → status → video URL. Submission may reserve funds. Do not run every catalog example in sequence.

## 5. Retrieve the result

Save the returned ID immediately. Poll the matching operation's status route using the same account. Response formats differ:

| Family | Identifier and result |
|---|---|
| MARS text2video | `data.task_id`, `data.task_status`; successful output at `data.task_result.videos[0].url` |
| Make jobs facade | `data.taskId`, `data.status`; output at `data.result.downloadUrl` |
| Other operations | Follow the module contract: synchronous response, separate task, or another output shape |

Bound your poll count and wait time. Keep the ID when the wait expires and check it later. On a submission timeout, `5xx`, or missing ID, **do not automatically repeat POST**: the server may have accepted the task. Check history and contact [support](/en/docs/contacts). The payment API's `Idempotency-Key` does not make arbitrary generation routes idempotent.

Verify that the result is accessible. Download and decode media; inspect text responses. Reconcile the final charge against [transactions](/en/docs/billing). Estimate, reservation and final cost can differ.

## Python: verify your connection

Uses the standard library with no extra packages. This example only reads the balance.

```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")})
```

For a generation JSON request, set `method="POST"`, `data=json.dumps(payload).encode()` and `Content-Type: application/json`. Take the payload, submit path and status path from the module guide. Do not add automatic task-creation retries.

## JavaScript: verify your connection

For server-side Node.js with built-in `fetch`. This example only reads the balance.

```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 });
```

For a generation JSON request, add `method: "POST"`, `body: JSON.stringify(payload)` and `Content-Type: application/json`. Before continuing, check both HTTP status and the contract's success/error fields.

## Share documentation with AI

Each section supports opening, downloading and copying Markdown, and handing it to AI. Share the relevant family guide together with this connection guide. Insert the real API key only in your own environment after reviewing the generated code.