---
title: Быстрый старт
description: Запустите первую генерацию изображения через Clipia API за четыре шага — от получения ключа до готового результата.
---

Чтобы сгенерировать первое изображение через Clipia API, выполните четыре шага: получите API-ключ в личном кабинете, отправьте генерацию через `POST /v1/models/{model}`, дождитесь завершения (через вебхук или опрос статуса) и заберите готовый результат. Базовый URL — `https://api.clipia.ai`, все запросы асинхронные (очередь).

<Steps>
<Step>
### Получите API-ключ

Создайте ключ в личном кабинете clipia.ai: раздел **Консоль разработчика** (`/developer`) → вкладка **API-ключи** → **Создать ключ**. Полный ключ показывается **один раз** — сохраните его сразу в надёжном месте.

```bash
export CLIPIA_KEY=clipia_live_xxxxxxxxxxxxxxxxxxxxxx
```

<Callout type="warn" title="Ключ — это серверный секрет">
Не размещайте ключ в браузере, мобильных приложениях или публичных репозиториях. Используйте его только из защищённого серверного окружения.
</Callout>
</Step>

<Step>
### Поставьте генерацию

Отправьте `POST /v1/models/{model}` с телом `input`. Slug модели берите из `GET /v1/models`. Заголовок `Idempotency-Key` (UUID v4) делает повторные отправки при сетевых сбоях безопасными.

<Tabs items={['cURL', 'TypeScript', 'Python']}>
<Tab value="cURL">

```bash
curl -X POST https://api.clipia.ai/v1/models/nano-banana-2 \
  -H "Authorization: Bearer $CLIPIA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f3a1c7e-2b41-4d2a-9c0e-1200304cf45b" \
  -d '{
    "input": { "prompt": "a sunset over mountains, cinematic" },
    "webhook_url": "https://your-server.com/clipia/webhook"
  }'
```

</Tab>
<Tab value="TypeScript">

```ts
import { Clipia } from "clipia-ai";

const clipia = new Clipia({ apiKey: process.env.CLIPIA_KEY });

const request = await clipia.models.submit("nano-banana-2", {
  input: { prompt: "a sunset over mountains, cinematic" },
  webhookUrl: "https://your-server.com/clipia/webhook",
});

console.log(request.requestId, request.status);
```

</Tab>
<Tab value="Python">

```python
import os
from clipia import Clipia

clipia = Clipia(api_key=os.environ["CLIPIA_API_KEY"])

request = clipia.models.submit(
    "nano-banana-2",
    input={"prompt": "a sunset over mountains, cinematic"},
    webhook_url="https://your-server.com/clipia/webhook",
)

print(request.request_id, request.status)
```

</Tab>
</Tabs>

Ответ содержит `request_id` и ссылки для опроса:

```json
{
  "request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",
  "status": "IN_QUEUE",
  "queue_position": 0,
  "status_url":   "https://api.clipia.ai/v1/requests/764cabcf-.../status",
  "response_url": "https://api.clipia.ai/v1/requests/764cabcf-...",
  "cost": 12
}
```

Поле `cost` — фиксированная цена операции в **кредитах**, известная заранее. Кредиты резервируются при отправке и окончательно списываются только при успехе; при ошибке возвращаются полностью.
</Step>

<Step>
### Дождитесь завершения

Есть два способа узнать, что генерация готова.

**Вариант A — вебхук (рекомендуется).** Если при отправке передан `webhook_url`, Clipia сам пришлёт `POST` на ваш сервер по завершении — опрашивать ничего не нужно. Доставка подписана HMAC-SHA256.

**Вариант B — опрос статуса.** Периодически запрашивайте `status_url`:

<Tabs items={['cURL', 'TypeScript', 'Python']}>
<Tab value="cURL">

```bash
curl https://api.clipia.ai/v1/requests/764cabcf-.../status \
  -H "Authorization: Bearer $CLIPIA_KEY"
```

</Tab>
<Tab value="TypeScript">

```ts
const result = await clipia.requests.wait(request.requestId);
console.log(result.status); // "COMPLETED"
```

</Tab>
<Tab value="Python">

```python
result = clipia.requests.wait(request.request_id)
print(result.status)  # "COMPLETED"
```

</Tab>
</Tabs>

```json
{ "request_id": "764cabcf-...", "status": "IN_PROGRESS", "progress": 45 }
```

| Статус | Что значит |
|--------|------------|
| `IN_QUEUE` | в очереди |
| `IN_PROGRESS` | выполняется (`progress` 0–100) |
| `COMPLETED` | готово — забирайте результат |
| `FAILED` | ошибка, кредиты возвращены |
| `CANCELED` | отменено вне публичного API (терминальный статус) |
</Step>

<Step>
### Заберите результат

Когда `status == COMPLETED`, запросите результат через `response_url`:

```bash
curl https://api.clipia.ai/v1/requests/764cabcf-... \
  -H "Authorization: Bearer $CLIPIA_KEY"
```

```json
{
  "request_id": "764cabcf-...",
  "status": "COMPLETED",
  "model": "nano-banana-2",
  "output": {
    "images": [
      { "url": "https://media.clipia.ai/works/....png", "width": 1024, "height": 1024 }
    ]
  },
  "cost": 12,
  "created_at": "2026-06-01T12:00:00Z",
  "completed_at": "2026-06-01T12:00:18Z"
}
```

Для видео-моделей `output` содержит `video: { url, width, height, duration }`. Все медиа-URL ведут на CDN `media.clipia.ai`.
</Step>
</Steps>

<Callout type="info" title="Дальше">
Хотите проверить интеграцию без списания кредитов? Используйте тестовый ключ `clipia_test_*` — см. страницу «Тестовый режим». Перед боевым запуском пройдитесь по разделу «Рекомендации».
</Callout>