---
title: Быстрый старт
description: Первая генерация изображения через Clipia API за четыре шага — от создания ключа до готового результата, с примерами на cURL, TypeScript и Python.
icon: Rocket
---

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

<Steps>
<Step>
### Создайте API-ключ

Откройте [консоль разработчика](/ru/developer), вкладка **API-ключи** → **Создать ключ**. Полный ключ показывается **один раз** — сохраните его сразу. Во всех примерах документации ключ лежит в переменной окружения `CLIPIA_KEY`.

```bash
export CLIPIA_KEY=clipia_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

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

<Callout type="info" title="Нужна активная подписка">
Боевой ключ `clipia_live_` генерирует, пока у аккаунта активна подписка, иначе запрос вернёт `402 subscription_required`. Чтобы отладить код без оплаты, создайте тестовый ключ `clipia_test_` — см. [«Тестовый режим»](/ru/docs/getting-started/sandbox).
</Callout>
</Step>

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

Отправьте `POST /v1/models/{model}` с телом `input`. Slug модели берите из `GET /v1/models` или из [каталога моделей](/ru/docs/api-reference/models). Заголовок `Idempotency-Key` делает повторную отправку после сетевого сбоя безопасной: вторая задача не создастся.

<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 { createClient } from "clipia-ai";

const clipia = createClient({ apiKey: process.env.CLIPIA_KEY! });

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

console.log(job.request_id, job.status, job.cost);
```

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

```python
import os
from clipia import Clipia

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

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

print(job.request_id, job.status, job.cost)
```

</Tab>
</Tabs>

SDK сами добавляют `Idempotency-Key` к каждой отправке. Ответ содержит `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` — сколько **кредитов** зарезервировано под задачу. При успехе они списываются, при ошибке генерации возвращаются полностью. Узнать цену до отправки можно через [оценку стоимости](/ru/docs/api-reference/estimate).
</Step>

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

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

**Вебхук (рекомендуется).** Если при отправке передан `webhook_url`, Clipia пришлёт `POST` на ваш сервер, когда задача завершится. Доставка подписана HMAC-SHA256 — см. [«Вебхуки»](/ru/docs/api-reference/webhooks).

**Опрос статуса.** Запрашивайте `status_url` раз в 1–2 секунды, пока статус не станет терминальным:

<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
// subscribe() сам отправляет задачу и опрашивает статус до завершения
const result = await clipia.subscribe("nano-banana-2", {
  input: { prompt: "a sunset over mountains, cinematic" },
  onQueueUpdate: (s) => console.log(s.status, s.progress),
});

console.log(result.status); // "COMPLETED"
```

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

```python
# subscribe() сам отправляет задачу и опрашивает статус до завершения
result = clipia.subscribe(
    "nano-banana-2",
    {"prompt": "a sunset over mountains, cinematic"},
    on_queue_update=lambda s: print(s.status, s.progress),
)

print(result.status)  # "COMPLETED"
```

</Tab>
</Tabs>

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

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

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

Когда статус `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/....webp",
        "original_url": "https://media.clipia.ai/....png"
      }
    ]
  },
  "cost": 12,
  "created_at": "2026-10-09T12:00:00Z",
  "completed_at": "2026-10-09T12:00:18Z"
}
```

`url` — оптимизированная копия для показа, `original_url` — исходный файл. Для видео `output` содержит `video: { url, original_url, thumbnail_url }`, для аудио — `audio: { url }`. Подробности — на странице [«Результат»](/ru/docs/api-reference/result).
</Step>
</Steps>

<Callout type="info" title="Дальше">
Отладьте интеграцию без списания кредитов на [тестовом ключе](/ru/docs/getting-started/sandbox). Перед боевым запуском прочитайте [рекомендации](/ru/docs/guides/best-practices).
</Callout>