# Účet

> Zjištění zůstatku kreditu, členství v organizacích a nákladů konverzací uživatele API klíče a verze serveru.

Tyto endpointy popisují účet, ke kterému API klíč patří: kolik má kreditů, do kterých
organizací patří a kolik stála konverzace. Endpoint verze vám řekne, jaké vydání AYETO
na serveru běží.

## Kredity

Všechno, co používá AI model (chat, generování obrázků, řeč, převod dokumentů), se
platí v **kreditech**. Cena každého volání vychází z použitého modelu a z množství
zpracovaného vstupu a výstupu; relativní představu o ceně najdete u
[modelů](models-and-tools.md#cenove-urovne).

Existují dva druhy zůstatku:

- **Osobní kredity** patří uživateli. Platí se z nich všechno, co se děje mimo
  organizaci. Zjistíte je pomocí [zjištění zůstatku kreditu](#zjisteni-zustatku-kreditu).
- **Kredity organizace** platí práci v organizaci, například požadavek
  [chatu](chat.md) s `organization_id`. Podle toho, jak je organizace nastavená, člen
  buď čerpá ze sdíleného zůstatku organizace, nebo má v ní individuální rozpočet.
  Zjistíte je pomocí [výpisu členství v organizacích](#vypis-clenstvi-v-organizacich).

Požadavek se odmítne, když je zůstatek, ze kterého by čerpal, vyčerpaný. Kontrola
proběhne před zahájením práce a skutečná cena se účtuje po jejím dokončení, takže
zůstatek může skončit mírně pod nulou. Když zůstatek dojde, požadavek selže s `422`
a detailem `not enough user credit` nebo `not enough organization credit`.

Kredity se doplňují v aplikaci AYETO.

## Zjištění zůstatku kreditu

| | |
|---|---|
| Endpoint | `POST /api/v3/user_credit/get_self` |
| Rozsah | jakýkoli API klíč |
| Limit požadavků | [default](conventions.md#limity-pozadavku) |

Vrací osobní zůstatek kreditu uživatele API klíče. Zůstatky v organizacích vrací
[výpis členství v organizacích](#vypis-clenstvi-v-organizacich).

`GET /api/v3/user_credit/get_self` dál funguje a vrací totéž; obě metody sdílejí
jeden čítač limitu požadavků.

### Požadavek

Není potřeba žádné tělo ani parametry. Tělo JSON, pokud nějaké pošlete, se ignoruje.

### Odpověď

`200 OK` s:

| Pole | Typ | Popis |
|---|---|---|
| `credits` | číslo | Osobní zůstatek kreditu. Může být mírně záporný, viz [kredity](#kredity). |

### Chyby

Tento endpoint nemá žádné chyby specifické pro sebe. Chyby autentizace, limitů
požadavků a serveru jsou popsány v [konvencích](conventions.md#chyby).

### Příklad

```bash
curl -X POST "https://ayeto.ai/api/v3/user_credit/get_self" \
  -H "uni-api-key: $AYETO_API_KEY"
```

```json
{
  "credits": 1843.27
}
```

## Výpis členství v organizacích

| | |
|---|---|
| Endpoint | `POST /api/v3/organization/membership/get_self` |
| Rozsah | jakýkoli API klíč |
| Limit požadavků | [default](conventions.md#limity-pozadavku) |

Vrací organizace, jejichž členem uživatel API klíče je, s rolí uživatele a kredity,
které má uživatel v každé z nich k dispozici. Použijte `organization_id` odsud jako
`organization_id` požadavku [chatu](chat.md), chcete-li pracovat, a platit, v rámci
této organizace.

### Požadavek

Tělo není potřeba.

### Odpověď

`200 OK` s polem členství, prázdným, když uživatel není členem žádné organizace:

| Pole | Typ | Popis |
|---|---|---|
| `organization_id` | UUID | Organizace. |
| `organization_name` | řetězec | Název organizace. |
| `user_id` | UUID | Uživatel API klíče. |
| `role` | řetězec | Role uživatele: `ayeto-org-admin` (administrátor), `ayeto-org-member` (člen) nebo `ayeto-org-guest` (host). |
| `individual_budget` | boolean | `true`, když má uživatel v organizaci individuální rozpočet; `false`, když čerpá ze sdíleného zůstatku organizace. |
| `credits` | číslo | Kredity, které má uživatel v této organizaci k dispozici: individuální rozpočet, když je `individual_budget` `true`, jinak sdílený zůstatek organizace. |
| `is_partner_admin` | boolean | `true` u administrátorského členství drženého jménem partnera, který organizaci spravuje. |
| `has_logo` | boolean | Zda má organizace logo. |
| `logo_id` | UUID nebo null | Identifikátor souboru s logem. |
| `logo_url` | řetězec | Veřejná URL loga, prázdná, když logo není. |

### Chyby

Tento endpoint nemá žádné chyby specifické pro sebe. Chyby autentizace, limitů
požadavků a serveru jsou popsány v [konvencích](conventions.md#chyby).

### Příklad

```bash
curl -X POST "https://ayeto.ai/api/v3/organization/membership/get_self" \
  -H "uni-api-key: $AYETO_API_KEY"
```

```json
[
  {
    "organization_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "organization_name": "Northwind Trading",
    "user_id": "6c5b4a39-2817-4f6e-9d5c-4b3a29180f7e",
    "role": "ayeto-org-member",
    "individual_budget": false,
    "credits": 25210.5,
    "is_partner_admin": false,
    "has_logo": true,
    "logo_id": "0f9e8d7c-6b5a-4938-8271-605f4e3d2c1b",
    "logo_url": "https://ayeto.ai/api/v1/public/file/read?id=0f9e8d7c-6b5a-4938-8271-605f4e3d2c1b&secret=3b8f1c2d9e7a4b6c"
  }
]
```

## Zjištění nákladů konverzace

| | |
|---|---|
| Endpoint | `POST /api/v3/usage/cost/conversation` |
| Rozsah | `ayeto.conversation` |
| Limit požadavků | [default](conventions.md#limity-pozadavku) |

Vrací kredity, které uživatel API klíče utratil v jedné [konverzaci](conversations.md):
volání modelu u všech jejích zpráv, včetně nástrojů, které používaly AI modely
(generování obrázků, čtení dokumentů, řeč). Počítá se jen vlastní útrata uživatele;
v konverzaci, které se účastnili i další lidé, je jejich využití vynecháno.

Náklady jsou součtem kreditů zaznamenaných u každého volání modelu v okamžiku jeho
vyúčtování, takže odpovídají tomu, co uživatel zaplatil, i když se cena modelu mezitím
změnila nebo byl model odebrán.

Konverzace, která neexistuje nebo ve které uživatel nic neutratil, vrací `0`.

### Požadavek

| Pole | Typ | Povinné | Popis |
|---|---|---|---|
| `conversation_id` | UUID | Ano | Konverzace. |

### Odpověď

`200 OK` s:

| Pole | Typ | Popis |
|---|---|---|
| `conversation_id` | UUID | Konverzace z požadavku. |
| `total_cost` | číslo | Kredity, které uživatel v konverzaci utratil. |

### Chyby

| Stav | `detail` | Příčina |
|---|---|---|
| `401` | `API key is invalid` | Klíči chybí rozsah `ayeto.conversation` (a nejde o klíč se všemi rozsahy), nebo klíč není platný. |
| `403` | `permission denied` | Účet uživatele nemá povoleno číst data o využití. |
| `422` | chyba validace | `conversation_id` chybí nebo není UUID. |

Chyby autentizace, limitů požadavků a serveru jsou popsány v
[konvencích](conventions.md#chyby).

### Příklad

```bash
curl -X POST "https://ayeto.ai/api/v3/usage/cost/conversation" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": "5e4d3c2b-1a09-4f8e-b7d6-c5b4a3928170"}'
```

```json
{
  "conversation_id": "5e4d3c2b-1a09-4f8e-b7d6-c5b4a3928170",
  "total_cost": 12.4816
}
```

## Zjištění verze serveru

| | |
|---|---|
| Endpoint | `POST /api/v3/version` |
| Rozsah | žádný, API klíč není potřeba |
| Limit požadavků | [static](conventions.md#limity-pozadavku) |

Vrací verzi vydání AYETO, které na serveru běží. Použijte ji pro diagnostiku a pro
ověření, že je server dosažitelný.

`GET /api/v3/version` dál funguje a vrací totéž; obě metody sdílejí jeden čítač limitu
požadavků (1 200 požadavků za minutu na IP adresu), což na kontroly dostupnosti
(health checks) stačí.

Každá odpověď API navíc nese vydání v hlavičce odpovědi `app-version`.

### Požadavek

Není potřeba žádné tělo ani parametry. Tělo JSON, pokud nějaké pošlete, se ignoruje.
Hlavička `uni-api-key` není potřeba.

### Odpověď

`200 OK` s:

| Pole | Typ | Popis |
|---|---|---|
| `app_version` | řetězec | Vydání AYETO, například `0.20.7`. Tuto verzi uvádějte v žádostech o podporu. |
| `version` | řetězec | Verze serverového frameworku. |
| `run_id` | řetězec | Identifikátor běžícího serverového procesu. Mění se při každém restartu a liší se mezi instancemi serveru. |
| `app_deployment` | řetězec | Označení slotu nasazení, který odpověděl (například `BLUE` nebo `GREEN`), `UNKNOWN`, když není nastaveno. |

### Příklad

```bash
curl -X POST "https://ayeto.ai/api/v3/version"
```

```json
{
  "version": "2.0.0",
  "run_id": "b7c6d5e4-f3a2-4b1c-8d9e-0f1a2b3c4d5e",
  "app_version": "0.20.7",
  "app_deployment": "BLUE"
}
```