# QOYO Agent API — установка навыка

Передайте агенту **эти файлы** и ключ `qoyo_sk_…` из [кабинета QOYO](https://qoyo.ru/cabinet?tab=developers).

## 1. Куда положить файлы

| Файл | Куда |
|------|------|
| `SKILL.md` | `.cursor/skills/qoyo-agent-api/SKILL.md` или корень проекта агента |
| `mcp-qoyo-agent.json` | конфиг MCP-клиента |
| `.env` | переменные окружения (см. ниже) |

## 2. Переменные окружения

```env
QOYO_API_KEY=qoyo_sk_…
QOYO_API_BASE=https://qoyo.ru/api/v1
```

## 3. Единственный источник правды по параметрам и цене

**Не угадывайте** duration, resolution, quality и лимиты файлов из памяти.

| Шаг | Запрос | Зачем |
|-----|--------|--------|
| 1 | `GET /catalog/{modelId}` | `fields`, `defaults`, **`pricing`**, **`fieldMeta`** |
| 2 | `POST /price` | **`credits`** и **`billingInput`** (нормализованный input) |
| 3 | `POST /generate` | Тот же `model` + тот же `input`, что в шаге 2 |

## 4. Загрузка файлов

1. Публичный `https://` URL → сразу в `input`.
2. Локальный файл → `POST /uploads` multipart с `modelId` + `fieldName` → `absoluteUrl` в `input`.

## 5. Модели с особыми правилами

- **Kling AI Avatar** — не задавайте `duration`; цена по `audio_url`.
- **Grok Imagine Video 1.5** (`grok-imagine-video-1-5-preview`) — обязателен `image_urls` (1 изображение, до 20 MB); цена: `duration` × тариф по `resolution` + доплата за изображение.

## 6. Чеклист агента перед generate

- [ ] `GET /catalog/{modelId}` прочитан
- [ ] Все обязательные `fields` заполнены
- [ ] Файлы в лимитах `fieldMeta.upload`
- [ ] `POST /price` выполнен
- [ ] `input` для generate **идентичен** price (или равен `billingInput`)
- [ ] `credits` ≤ баланс из `GET /me`
- [ ] `idempotencyKey` при повторе запроса

## 7. Документы

- `QOYO_AGENT_API.md` — полное API EN/RU  
- OpenAPI: `https://qoyo.ru/api/v1/openapi.json`