---
name: qoyo-agent-api
description: Generate images, video, audio, and chat via QOYO studio API. Use catalog pricing/fieldMeta and POST /price before every generate — no guessed costs.
---

# QOYO Agent API

## Critical rules (pricing accuracy)

1. **Never guess** price, duration, resolution, or file limits.
2. **`GET /catalog/{modelId}`** — read `fields`, `defaults`, **`pricing`**, **`fieldMeta`**.
3. **`POST /price`** — mandatory; **`credits`** and **`billingInput`** are the only billable truth.
4. **`POST /generate`** — same `model` + same `input` as `/price` (or use `billingInput` verbatim).
5. Uploads: use **`fieldMeta.upload`** (`maxMb`, `maxFiles`, `acceptMimeTypes`); call `POST /uploads` with `modelId` + `fieldName`.

Full setup: https://qoyo.ru/docs/AGENT_SETUP.md

## Environment

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

## Workflow

```
GET /me
GET /catalog
GET /catalog/{modelId}   ← pricing + fieldMeta + upload limits
POST /uploads            ← if local files (optional)
POST /price              ← credits + billingInput
POST /generate           ← same input; idempotencyKey on retry
GET /tasks/{id}?sync=1
```

## Reading `pricing` (from catalog detail)

| billingMode | Meaning |
|-------------|---------|
| `composite_table` | Fixed USD per combination (duration, quality, resolution, …) |
| `params_usd` | Extra USD per option value (e.g. resolution 1K/2K/4K) |
| `per_second_video` | duration × $/s × mode × sound |
| `per_second_motion_fixed` | Fixed seconds (not client duration) |
| `seedance2_metered` | Seconds × rate; +input video if reference_video_urls |
| `video_second_metered` | duration (1–15 s) × $/s by resolution (480p/720p); +input image fee when `image_urls` set |
| `lip_sync_audio` | Avatar: bill from audio_url probe |
| `chat_tokens` | Chat models — token/message estimate |

Always follow **`pricing.agentNotes`** for the model.

## Reading `fieldMeta.upload`

| Field | Action |
|-------|--------|
| `supported: true` | May use `POST /uploads` or public HTTPS URL |
| `supported: false` | Text/select only, or URL you host elsewhere |
| `maxMb` / `maxFiles` | Hard limits for uploads |
| `affectsPricing: true` | Must be set correctly before `/price` |

## Model-specific

- **Grok Imagine Video 1.5** (`grok-imagine-video-1-5-preview`): image-to-video; **`video_second_metered`**. Required: `image_urls` with exactly **1** image (max 20 MB). Price drivers: `duration` (1–15 s integer), `resolution` (`480p`|`720p`), plus flat input-image fee when `image_urls` is non-empty. Upload via `POST /uploads` with `modelId=grok-imagine-video-1-5-preview`, `fieldName=image_urls`.
- **Kling AI Avatar** (`kling/ai-avatar-*`): do not set `duration`; price from `audio_url`.
- **Seedance 2**: no mixing frame URLs with reference_* arrays.
- **GPT Image 2**: `aspect_ratio` + `resolution` caps enforced server-side.
- **Gemini Omni video**: `duration`, `resolution`, `video_clip_url` drive tier.

## Errors

- **402** — top up at `/cabinet`
- **429** — wait `Retry-After`
- **422** — fix input per catalog; compare with `billingInput` from a successful `/price`

## References

- Catalog + pricing live: `GET /catalog/{modelId}`
- Docs: `https://qoyo.ru/docs/QOYO_AGENT_API.md`

## RU (кратко)

Каталог → `pricing` + `fieldMeta` → `/price` (`billingInput`) → `/generate` с тем же input. Grok Imagine Video 1.5 — обязателен `image_urls` (1 фото), цена по `duration` и `resolution`. Kling Avatar — цена по `audio_url`.