> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradium.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Résidence des données

> Ancrez vos sessions vocales dans l'UE ou aux États-Unis avec eu.api.gradium.ai et us.api.gradium.ai

Gradium exécute l'inférence à la fois dans l'Union européenne et aux
États-Unis. Par défaut, vous appelez un endpoint unique, `api.gradium.ai`, et
les requêtes sont acheminées vers le cluster le plus proche. Pour la plupart
des clients, cela signifie déjà qu'en pratique, les sessions sont traitées à
proximité.

La résidence des données s'adresse aux cas où « en pratique » ne suffit pas.
Une fois activée sur votre offre, le traitement dans une région choisie
devient une garantie appliquée à chaque requête : vos sessions ne sont jamais
réacheminées hors de cette région, et chaque réponse vous le confirme.

## Endpoints

| Endpoint | Comportement |
| - | - |
| `api.gradium.ai` | Par défaut. Acheminé vers le cluster le plus proche ; aucun engagement de résidence. |
| `eu.api.gradium.ai` | Ancré dans l'UE. Pour les organisations inscrites à la résidence des données UE, les sessions sont traitées dans l'UE de façon garantie. |
| `us.api.gradium.ai` | Ancré aux États-Unis. Pour les organisations inscrites à la résidence des données US, les sessions sont traitées aux États-Unis de façon garantie. |

Les trois endpoints exposent la même API : même clé API, mêmes routes, mêmes
formats de requête et de réponse. Seul l'hôte change.

```
https://eu.api.gradium.ai/api      wss://eu.api.gradium.ai/api
https://us.api.gradium.ai/api      wss://us.api.gradium.ai/api
```

## Ce qui est garanti

Pour une organisation inscrite à la résidence des données dans une région :

* **L'inférence reste dans la région.** Les sessions de synthèse vocale,
  de transcription et de Speech-to-Speech, en WebSocket ou via les endpoints
  REST POST, s'exécutent sur nos clusters de cette région.
* **Aucun basculement inter-régions.** En cas de charge, une session peut être
  servie par un autre cluster de la même région, mais jamais par un cluster
  situé en dehors.
* **Refus par défaut.** Si une requête ancrée atteint un jour un cluster d'une
  autre région, elle est refusée plutôt que traitée hors de sa région (voir
  [Refus](#refus)).
* **Les données de session sont écrites dans la région.** Les données de
  session que nous conservons (voir
  [Zéro rétention des données](/fr/guides/faq#comment-activer-la-zéro-rétention-des-données-)
  pour n'en conserver aucune) sont écrites par le cluster qui a servi la
  session.

## Résidence des données UE

`eu.api.gradium.ai` est servi par nos clusters européens. Pour une
organisation inscrite à la résidence UE, une session qui démarre sur l'un
d'eux reste en Europe : elle n'est jamais confiée à un cluster américain, et
une requête ancrée qui en atteindrait un est refusée.

La résidence UE est la plus complète des deux, car notre plan de contrôle,
qui gère les données de compte, est hébergé dans l'UE pour **tous** les
clients, inscrits ou non. Ainsi, pour une organisation ancrée dans l'UE,
l'audio traité pendant une session comme les métadonnées de compte associées
restent dans l'Union européenne.

## Résidence des données US

`us.api.gradium.ai` est servi par nos clusters américains, sur la côte Est et
la côte Ouest. Pour une organisation inscrite à la résidence US, les sessions
s'exécutent de façon garantie sur ces clusters et ne sont jamais réacheminées
vers l'UE.

<Note>
  La résidence US couvre l'**inférence** : l'audio et le texte de vos sessions.
  Notre plan de contrôle est hébergé dans l'UE pour tous les clients : les
  données de compte, les voix personnalisées et les dictionnaires de
  prononciation restent donc stockés dans l'UE, et les appels de gestion y sont
  toujours servis. Si vous avez également besoin du plan de contrôle aux
  États-Unis, contactez-nous pour un déploiement auto-hébergé.
</Note>

## Comment l'activer

<Note>
  La résidence des données est disponible sur nos offres payantes. Elle est
  activée sur votre offre par notre équipe ; il n'existe pas encore d'option en
  libre-service.
</Note>

### 1. Demandez-nous de l'activer

Contactez [support@gradium.ai](mailto:support@gradium.ai) en indiquant le nom
de votre organisation et la région souhaitée (`eu` ou `us`), puis choisissez
l'un des deux modes :

* **Explicite** (par défaut) : les sessions sont ancrées lorsque vous appelez
  l'endpoint régional. Les appels à `api.gradium.ai` conservent leur
  comportement actuel. Choisissez ce mode si seule une partie de votre trafic
  a besoin de la garantie.
* **Implicite** : toute votre organisation est ancrée dans sa région, quel
  que soit l'endpoint appelé. Choisissez ce mode si l'ensemble de votre usage
  est concerné.

Une organisation dispose d'au plus une région de résidence. Si différentes
parties de votre trafic nécessitent des régions différentes, utilisez le mode
explicite et choisissez l'endpoint pour chaque intégration.

### 2. Pointez votre intégration vers l'endpoint régional

<CodeGroup>
  ```python Python SDK theme={null}
  import gradium

  client = gradium.client.GradiumClient(
      api_key="your-api-key",
      base_url="https://eu.api.gradium.ai/api",  # or https://us.api.gradium.ai/api
  )
  ```

  ```bash cURL theme={null}
  # -D - prints the response headers, including x-gradium-residency
  curl -L -D - -o bonjour.wav -X POST https://eu.api.gradium.ai/api/post/speech/tts \
    -H "x-api-key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{"text": "Bonjour !", "voice_id": "YTpq7expH9539ERJ", "output_format": "wav", "only_audio": true}'
  ```

  ```text WebSocket theme={null}
  wss://eu.api.gradium.ai/api/speech/tts
  wss://us.api.gradium.ai/api/speech/asr
  ```
</CodeGroup>

En mode **implicite**, cette étape est facultative, puisque chaque endpoint
ancre vos sessions dans votre région, mais nous la recommandons tout de même.

### 3. Vérifiez

Chaque réponse indique la résidence effectivement appliquée à la requête :
vous pouvez donc la vérifier au lieu de vous fier à un nom d'hôte.

* **REST** : l'en-tête de réponse `x-gradium-residency`.
* **WebSocket** : le champ `residency` du message `ready`.

| Valeur | Signification |
| - | - |
| `pinned; zone=eu` | La garantie s'applique : cette session est traitée dans l'UE et n'en sortira pas. |
| `pinned; zone=us` | Idem, pour les États-Unis. |
| `best-effort; zone=eu` | La requête a abouti dans l'UE, mais votre organisation n'est pas inscrite : aucun engagement n'est pris. |
| `best-effort; zone=us` | Idem, pour les États-Unis. |
| `none` | Aucune région n'est concernée : endpoint par défaut, organisation non inscrite. |

```json TTS ready theme={null}
{
  "type": "ready",
  "request_id": "req_...",
  "model_name": "default",
  "residency": "pinned; zone=eu",
  "sample_rate": 48000,
  "frame_size": 3840
}
```

<Tip>
  Si vous dépendez de la garantie, vérifiez la présence de `pinned` dans votre
  client et traitez toute autre valeur comme une erreur de configuration.
  `best-effort` sur un endpoint régional signifie que la résidence n'a pas
  encore été activée sur votre offre.
</Tip>

## Refus

Une requête ancrée qui atteint un cluster hors de sa région est refusée au
lieu d'être traitée hors région :

* **REST** : `403 Forbidden`
* **WebSocket** : code de fermeture `1008` (violation de politique)

Les deux indiquent le motif
`This request must be sent to the <region> region endpoint.` En pratique,
cela se produit lorsqu'une organisation en mode **implicite** appelle un
endpoint qui n'est pas ancré dans sa région ; la solution consiste à utiliser
`eu.api.gradium.ai` ou `us.api.gradium.ai`.

## Résidence et zéro rétention des données

Les deux sont indépendantes et se combinent :

* La **résidence des données** détermine *où* vos requêtes sont traitées.
* La **zéro rétention des données** détermine *si* les payloads de requête et
  de réponse sont conservés ou non. Consultez la
  [FAQ](/fr/guides/faq#comment-activer-la-zéro-rétention-des-données-) pour l'activer.

Pour les détails de la certification ISO 27001 et les ressources de
sécurité, consultez [Sécurité et conformité](/fr/guides/security).

Pour un accord de traitement des données (DPA), contactez
[support@gradium.ai](mailto:support@gradium.ai).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.