> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elumenta.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Make your first Elumenta API call in under 5 minutes

## 1. Get your API key

API access is included in **VIP** and **Elite** plans.

1. Open [elumenta.ru/web](https://elumenta.ru/web) → **Profile → API Keys**
2. Click **Create Key**, give it a name
3. Copy the key — it starts with `nb_`

<Warning>
  Store your key securely. It provides full access to your token balance. Never expose it in client-side code.
</Warning>

## 2. The unified generation endpoint

All generations go through a **single endpoint**: `POST /api/v2/generate`

You pass any model slug + prompt + optional `params` object. This works for text, images, video, audio, and tools — same endpoint, different model slug.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://elumenta.ru/api/v2/generate \
    -H "Authorization: Bearer nb_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-5",
      "prompt": "Explain quantum computing in simple terms"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://elumenta.ru/api/v2/generate",
      headers={"Authorization": "Bearer nb_YOUR_API_KEY"},
      json={
          "model": "gpt-5",
          "prompt": "Explain quantum computing in simple terms"
      }
  )

  data = response.json()
  print(data["result_text"])
  print(f"Tokens spent: {data['tokens_spent']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://elumenta.ru/api/v2/generate", {
    method: "POST",
    headers: {
      "Authorization": "Bearer nb_YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "gpt-5",
      prompt: "Explain quantum computing in simple terms"
    })
  });

  const data = await response.json();
  console.log(data.result_text);
  ```
</CodeGroup>

## 3. Response structure

```json theme={null}
{
  "id": 18473,
  "status": "completed",
  "model_slug": "gpt-5",
  "result_text": "Quantum computing uses qubits that can exist in multiple states simultaneously...",
  "result_url": null,
  "thumbnail_url": null,
  "error": null,
  "tokens_spent": 3,
  "processing_ms": 1842,
  "result_metadata": null
}
```

| Field          | Description                             |
| -------------- | --------------------------------------- |
| `result_text`  | Text output (LLM responses)             |
| `result_url`   | File URL (images, video, audio)         |
| `tokens_spent` | Tokens deducted from balance            |
| `status`       | `completed` / `pending` / `failed`      |
| `id`           | Integer ID — use for polling async jobs |

## 4. Generate an image

Pass model-specific options in the `params` object:

```bash theme={null}
curl -X POST https://elumenta.ru/api/v2/generate \
  -H "Authorization: Bearer nb_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "A futuristic city at sunset, cyberpunk style",
    "params": {
      "size": "1024x1024",
      "format": "webp"
    }
  }'
```

Response:

```json theme={null}
{
  "id": 18491,
  "status": "completed",
  "model_slug": "dall-e-3",
  "result_url": "https://storage.elumenta.ru/generations/18491.webp",
  "tokens_spent": 7,
  "result_metadata": { "width": 1024, "height": 1024 }
}
```

## 5. Check balance

```bash theme={null}
curl https://elumenta.ru/api/v2/balance \
  -H "Authorization: Bearer nb_YOUR_API_KEY"
```

```json theme={null}
{
  "token_balance": 283,
  "plan": "vip",
  "plan_expires_at": "2026-04-08T00:00:00Z"
}
```

## 6. Poll async results

For video/slow models, `status` is `pending`. Poll `GET /api/v2/generate/{id}`:

```python theme={null}
import time

def wait_for_result(gen_id: int, headers: dict) -> dict:
    while True:
        r = requests.get(
            f"https://elumenta.ru/api/v2/generate/{gen_id}",
            headers=headers
        )
        data = r.json()
        if data["status"] in ("completed", "failed"):
            return data
        time.sleep(5)
```

## Next steps

<CardGroup cols={2}>
  <Card title="Full generate reference" icon="book" href="/en/api-reference/generate/create">
    All parameters and model-specific options
  </Card>

  <Card title="Streaming" icon="stream" href="/en/guides/streaming">
    Real-time SSE text streaming
  </Card>

  <Card title="Model catalog" icon="grid" href="/en/resources/models-catalog">
    All 52 slugs with costs
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/en/guides/error-handling">
    Retries, backoff, error codes
  </Card>
</CardGroup>