# Быстрый старт

СОЮЗ — единый API ко всем основным нейросетям: чат-модели (GPT, Claude, Gemini, Grok, DeepSeek), генерация картинок (Nano Banana, GPT Image) и видео (Veo, Kling, Seedance) через **один ключ** и **один формат**.

API совместим с OpenAI: если у тебя уже есть код под OpenAI SDK — поменяй две строки, и он работает.

```text
base_url = "https://api.souz.ai/v1"
api_key  = "sk-souz-..."
```

## 1. Получи API-ключ

Зарегистрируйся на [dash.souz.ai](https://dash.souz.ai), раздел **API-ключи** → «Создать ключ». Ключ показывается один раз — сохрани его.

## 2. Чат — через любой OpenAI SDK

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.souz.ai/v1",
    api_key="sk-souz-...",
)

resp = client.chat.completions.create(
    model="souz/gpt-5.4-mini",
    messages=[{"role": "user", "content": "Привет! Что ты умеешь?"}],
)
print(resp.choices[0].message.content)
print("потрачено кредитов:", resp.usage.cost)
```

То же на JavaScript:

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.souz.ai/v1",
  apiKey: "sk-souz-...",
});

const resp = await client.chat.completions.create({
  model: "souz/claude-sonnet-4-6",
  messages: [{ role: "user", content: "Привет!" }],
});
console.log(resp.choices[0].message.content);
```

Стриминг, картинки в сообщениях (vision), tools и reasoning — в разделе [Чат](/chat).

## 3. Картинка — один POST и короткий опрос

Генерация картинок и видео асинхронная: запрос сразу возвращает джобу, результат забираешь опросом или вебхуком.

```bash
curl https://api.souz.ai/v1/images/generations \
  -H "Authorization: Bearer sk-souz-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "souz/nano-banana-pro",
    "prompt": "уютный дом в горах на закате, кинематографичный свет",
    "aspect_ratio": "16:9",
    "resolution": "2K"
  }'
```

Ответ `202`:

```json
{
  "id": "job_a1b2c3...",
  "object": "image",
  "model": "souz/nano-banana-pro",
  "status": "queued",
  "price": 20,
  "created_at": 1781250000
}
```

Опрашивай джобу раз в 2–5 секунд:

```bash
curl https://api.souz.ai/v1/jobs/job_a1b2c3... \
  -H "Authorization: Bearer sk-souz-..."
```

Когда `status` станет `completed`, в `data[0].url` будет ссылка на файл:

```json
{
  "id": "job_a1b2c3...",
  "status": "completed",
  "price": 20,
  "data": [{ "url": "https://api.souz.ai/v1/files/res_....png?exp=...&sig=..." }]
}
```

> Файлы хранятся ~24 часа — скачивай результат сразу. Подробнее: [Джобы и результаты](/jobs).

## 4. Видео — так же

```bash
curl https://api.souz.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-souz-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "souz/veo3-fast",
    "prompt": "дрон пролетает над осенним лесом, утренний туман",
    "aspect_ratio": "16:9",
    "duration": "8"
  }'
```

Дальше тот же цикл: `GET /v1/jobs/{id}` → `completed` → `data[0].url` (mp4).

## Что дальше

- [Модели и цены](/models) — живой каталог со всеми возможностями
- [Чат](/chat) · [Картинки](/images) · [Видео](/videos)
- [Вебхуки](/webhooks) — результат без опроса
- [Ошибки](/errors) и [Лимиты](/limits)
- [Справочник API](/api-reference) — все эндпоинты на одной странице

## Для ИИ-агентов

- Индекс документации: [/llms.txt](/llms.txt)
- Вся документация одним файлом: [/llms-full.txt](/llms-full.txt)
- Любая страница в чистом Markdown: добавь `.md` к адресу (например `/chat.md`)