# Compte

> Lire le solde de crédits, les appartenances aux organisations et le coût des conversations de l'utilisateur de la clé API, ainsi que la version du serveur.

Ces endpoints décrivent le compte derrière la clé API : combien de crédits il possède, à quelles
organisations il appartient et ce qu'une conversation a coûté. L'endpoint de version vous indique
quelle release d'AYETO le serveur exécute.

## Crédits

Tout ce qui utilise un modèle d'IA (chat, génération d'images, voix, conversion de documents)
se paie en **crédits**. Le prix de chaque appel découle du modèle utilisé et de la
quantité d'entrée et de sortie traitée ; voir [modèles](models-and-tools.md#niveaux-de-prix)
pour une indication de prix relative.

Il existe deux types de solde :

- Les **crédits personnels** appartiennent à l'utilisateur. Ils paient tout ce qui est fait en dehors d'une
  organisation. Lisez-les avec [obtenir le solde de crédits](#obtenir-le-solde-de-credits).
- Les **crédits d'organisation** paient le travail effectué dans une organisation, par exemple une
  requête de [chat](chat.md) avec un `organization_id`. Selon la configuration de l'organisation,
  un membre puise soit dans le solde partagé de l'organisation, soit dans un budget individuel
  au sein de celle-ci. Lisez-les avec [lister les appartenances aux organisations](#lister-les-appartenances-aux-organisations).

Une requête est refusée lorsque le solde sur lequel elle puiserait est épuisé. La vérification a lieu
avant le début du travail, et le coût réel est débité une fois le travail terminé ; un
solde peut donc finir légèrement en dessous de zéro. Lorsqu'un solde est épuisé, la requête échoue avec
`422` et le détail `not enough user credit` ou `not enough organization credit`.

Les crédits s'ajoutent dans l'application AYETO.

## Obtenir le solde de crédits

| | |
|---|---|
| Endpoint | `POST /api/v3/user_credit/get_self` |
| Portée | n'importe quelle clé API |
| Limite de débit | [par défaut](conventions.md#limites-de-debit) |

Renvoie le solde de crédits personnel de l'utilisateur de la clé API. Les soldes d'organisation sont
renvoyés par [lister les appartenances aux organisations](#lister-les-appartenances-aux-organisations).

`GET /api/v3/user_credit/get_self` fonctionne toujours et renvoie la même chose ; les deux méthodes partagent
un même compteur de limite de débit.

### Requête

Aucun corps ni aucun paramètre n'est nécessaire. Un corps JSON, si vous en envoyez un, est ignoré.

### Réponse

`200 OK` avec :

| Champ | Type | Description |
|---|---|---|
| `credits` | nombre | Solde de crédits personnel. Peut être légèrement négatif, voir [crédits](#credits). |

### Erreurs

Cet endpoint n'a pas d'erreurs spécifiques. Les erreurs d'authentification, de limite de débit et du serveur
sont décrites dans les [conventions](conventions.md#erreurs).

### Exemple

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

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

## Lister les appartenances aux organisations

| | |
|---|---|
| Endpoint | `POST /api/v3/organization/membership/get_self` |
| Portée | n'importe quelle clé API |
| Limite de débit | [par défaut](conventions.md#limites-de-debit) |

Renvoie les organisations dont l'utilisateur de la clé API est membre, avec le rôle de l'utilisateur et
les crédits dont il dispose dans chacune. Utilisez l'`organization_id` renvoyé ici comme
`organization_id` d'une requête de [chat](chat.md) pour travailler, et payer, au sein de cette organisation.

### Requête

Aucun corps n'est nécessaire.

### Réponse

`200 OK` avec un tableau d'appartenances, vide lorsque l'utilisateur n'est membre d'aucune
organisation :

| Champ | Type | Description |
|---|---|---|
| `organization_id` | UUID | L'organisation. |
| `organization_name` | chaîne | Nom de l'organisation. |
| `user_id` | UUID | L'utilisateur de la clé API. |
| `role` | chaîne | Le rôle de l'utilisateur : `ayeto-org-admin` (administrateur), `ayeto-org-member` (membre) ou `ayeto-org-guest` (invité). |
| `individual_budget` | booléen | `true` lorsque l'utilisateur dispose d'un budget individuel dans l'organisation ; `false` lorsqu'il puise dans le solde partagé de l'organisation. |
| `credits` | nombre | Crédits dont dispose l'utilisateur dans cette organisation : le budget individuel lorsque `individual_budget` vaut `true`, sinon le solde partagé de l'organisation. |
| `is_partner_admin` | booléen | `true` pour une appartenance d'administrateur détenue pour le compte du partenaire qui gère l'organisation. |
| `has_logo` | booléen | Indique si l'organisation a un logo. |
| `logo_id` | UUID ou null | Identifiant du fichier du logo. |
| `logo_url` | chaîne | URL publique du logo, vide s'il n'y en a pas. |

### Erreurs

Cet endpoint n'a pas d'erreurs spécifiques. Les erreurs d'authentification, de limite de débit et du serveur
sont décrites dans les [conventions](conventions.md#erreurs).

### Exemple

```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"
  }
]
```

## Obtenir le coût d'une conversation

| | |
|---|---|
| Endpoint | `POST /api/v3/usage/cost/conversation` |
| Portée | `ayeto.conversation` |
| Limite de débit | [par défaut](conventions.md#limites-de-debit) |

Renvoie les crédits que l'utilisateur de la clé API a dépensés dans une [conversation](conversations.md) :
les appels de modèle de tous ses messages, y compris les outils qui ont utilisé des modèles d'IA (génération
d'images, lecture de documents, voix). Seules les dépenses de l'utilisateur lui-même sont comptées ; dans une
conversation à laquelle d'autres personnes ont aussi participé, leur consommation est exclue.

Le coût est la somme des crédits enregistrés pour chaque appel de modèle au moment où il a été facturé ; il
correspond donc à ce que l'utilisateur a payé, même si le prix d'un modèle a changé ou si le modèle a
été supprimé depuis.

Une conversation qui n'existe pas, ou dans laquelle l'utilisateur n'a rien dépensé, renvoie `0`.

### Requête

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `conversation_id` | UUID | Oui | La conversation. |

### Réponse

`200 OK` avec :

| Champ | Type | Description |
|---|---|---|
| `conversation_id` | UUID | La conversation indiquée dans la requête. |
| `total_cost` | nombre | Crédits dépensés par l'utilisateur dans la conversation. |

### Erreurs

| Statut | `detail` | Cause |
|---|---|---|
| `401` | `API key is invalid` | La clé n'a pas la portée `ayeto.conversation` (et n'est pas une clé « toutes les portées »), ou n'est pas valide. |
| `403` | `permission denied` | Le compte de l'utilisateur n'est pas autorisé à lire les données de consommation. |
| `422` | erreur de validation | `conversation_id` est absent ou n'est pas un UUID. |

Les erreurs d'authentification, de limite de débit et du serveur sont décrites dans les
[conventions](conventions.md#erreurs).

### Exemple

```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
}
```

## Obtenir la version du serveur

| | |
|---|---|
| Endpoint | `POST /api/v3/version` |
| Portée | aucune, pas de clé API nécessaire |
| Limite de débit | [statique](conventions.md#limites-de-debit) |

Renvoie la version de la release d'AYETO que le serveur exécute. Utilisez-la pour le diagnostic et pour
vérifier que le serveur est joignable.

`GET /api/v3/version` fonctionne toujours et renvoie la même chose ; les deux méthodes partagent un même compteur
de limite de débit (1 200 requêtes par minute et par adresse IP), ce qui suffit pour les contrôles de santé.

Chaque réponse de l'API indique aussi la release dans l'en-tête de réponse `app-version`.

### Requête

Aucun corps ni aucun paramètre n'est nécessaire. Un corps JSON, si vous en envoyez un, est ignoré.
L'en-tête `uni-api-key` n'est pas nécessaire.

### Réponse

`200 OK` avec :

| Champ | Type | Description |
|---|---|---|
| `app_version` | chaîne | La release d'AYETO, par exemple `0.20.7`. C'est la version à indiquer dans les demandes d'assistance. |
| `version` | chaîne | Version du framework du serveur. |
| `run_id` | chaîne | Identifiant du processus serveur en cours d'exécution. Il change à chaque redémarrage et diffère entre les instances du serveur. |
| `app_deployment` | chaîne | Libellé de l'emplacement de déploiement qui a répondu (par exemple `BLUE` ou `GREEN`), `UNKNOWN` s'il n'est pas défini. |

### Exemple

```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"
}
```