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

# Présentation du SDK Python

> Client Python officiel pour l’API Phaseo Gateway

Installez depuis PyPI le package publié [~~phaseo~~](https://pypi.org/project/phaseo/).

Le SDK Python Phaseo fournit les clients synchrone `Phaseo` et asynchrone natif `AsyncPhaseo`.

## Requêtes asynchrones natives

```python theme={null}
import asyncio
from phaseo import AsyncPhaseo

async def main():
    async with AsyncPhaseo() as client:
        response = await client.responses.create({"model": "openai/gpt-5-nano", "input": "Hello"})
        print(response.output_text, response.request_id, response.trace_url)

asyncio.run(main())
```

Utilisez `async for event in client.responses.stream(request)` pour les événements texte analysés.
L’annulation native asyncio arrête HTTP et les interrogations. Les espaces de ressources couvrent texte,
images, audio, musique, vidéo, lots, fichiers, modèles, embeddings, OCR, reclassement, analyse,
modération et décisions ; utilisez `await client.request(...)` pour les autres opérations HTTP.
Les clients HTTPX injectés restent sous la responsabilité de l’appelant.

Les deux clients prennent en charge `with_options(timeout=30, max_retries=2)` sans modifier le
client original. Les délais HTTPX limitent l’inactivité réseau en secondes. Les tentatives sont
nulles par défaut et concernent uniquement GET/HEAD avant lecture de la réponse, jamais les soumissions.
`PhaseoHTTPError` expose le corps, le code, l’identifiant de requête, l’URL de trace et le délai de nouvelle tentative.

Lors de la mise à niveau, remplacez les captures de `urllib.error.HTTPError` pour les requêtes JSON synchrones
par `PhaseoHTTPError` (ou `httpx.HTTPStatusError`), et les erreurs de connexion
par `httpx.TransportError`. `error.status` est le statut HTTP ; `error.code` est
le code d’erreur API.

## Fonctionnalités supplémentaires

Les ressources de tâches exposent des références `start` et `resume` avec `result`, `events` et
`to_dict`. Attendez les méthodes asynchrones et parcourez les événements avec `async for`.
Seuls vidéo et lots permettent l’annulation distante. Diffusez les médias avec
`videos.stream_content(id)` et les lots avec `batches.results(id)`. L’outil synchrone
`download_to(chunks, binary_file)` écrit sans mettre en tampon le fichier entier.
Les téléversements acceptent des octets, des objets `Path`, des objets fichier et des tuples fichier HTTPX.

`responses.parse(request, PydanticModel)` valide la sortie JSON terminée ;
configurez explicitement le format de réponse serveur. `collect_stream` et
`collect_async_stream` accumulent les événements texte analysés et l’utilisation.
`check_model_capabilities(id, input_types=..., output_types=..., endpoints=...,
parameters=..., parameter_values=...)` vérifie ensemble les capacités annoncées et les contraintes
scalaires d’une offre fournisseur disponible. Les données inconnues font échouer la vérification préalable.

Pour les sélecteurs de modèles et éditeurs de paramètres, utilisez les métadonnées actuelles des points d’accès :

```python theme={null}
support = client.models.check_parameters(
    "openai/gpt-5",
    {"temperature": 0.7, "top_p": 0.9},
    endpoint="responses",
)
```

Chaque paramètre porte `supported`, `partial`, `unsupported` ou `unknown`,
avec les routes correspondantes et les problèmes de contraintes pour l’affichage en ligne.
`client.models.capabilities(model_id)` renvoie la réponse complète des capacités
du point d’accès. `AsyncPhaseo` expose les mêmes méthodes attendables.

Pour les tests locaux, injectez `phaseo.testing.MockTransport` via `httpx.Client` ou
`httpx.AsyncClient`. Les requêtes imprévues échouent localement ; appelez `assert_done()` pour
vérifier tous les jeux de test. Ils ne vérifient pas le comportement réel des fournisseurs.
Les salons Phaseo exportent le code exécutable de la requête via **Obtenir le code**.

## Fonctionnalités

* Modèles de requête typés générés à partir de la spécification OpenAPI.
* Méthodes intégrées pour le chat, les réponses, les messages, les images, l’audio, les embeddings, les modérations, les fichiers, les lots, les générations et les tâches vidéo asynchrones.
* Méthodes de streaming pour le texte, les réponses et les messages (itérateurs ~~stream\_\*~~).
* Fonctions du plan de contrôle pour consulter les modèles, endpoints et organisations, explorer et calculer les tarifs, gérer le cycle de vie des clés API et des espaces de travail, vérifier la clé actuelle et consulter l’état, les fournisseurs, les crédits, l’activité et les analyses.

## Exemple rapide

```python theme={null}
from phaseo import Phaseo

client = Phaseo(api_key="your-api-key")

response = client.generate_response(
    {
        "model": "openai/gpt-5-nano",
        "input": "Reply with: python sdk works",
    }
)

print(response.get("id"))
```

## Attendre la musique, les vidéos ou les lots

```python theme={null}
import os

music = client.music.generate_and_wait(
    {"model": os.environ["PHASEO_MUSIC_MODEL"], "prompt": "Gentle instrumental piano"},
    timeout=600,
    on_poll=lambda job: print(job["id"], job["status"]),
)
```

Utilisez `videos.generate_and_wait(request, **options)` pour les vidéos et `batches.create_and_wait(request, **options)` pour les lots. Ces outils synchrones soumettent une seule fois et renvoient la réponse complète, en interrogeant uniquement si nécessaire. `JobFailedError.response` conserve les détails des tâches échouées, annulées ou expirées. Les lots terminés peuvent contenir des requêtes individuelles échouées.

Chaque ressource accepte `wait(id, **options)` pour reprendre une tâche existante et renvoyer toute réponse finale. La musique expose aussi les méthodes directes `create(request)` et `retrieve(id)`.

Les options sont `interval` (secondes ; défaut 5, minimum 0.25), `timeout` (secondes ; défaut 1800), `on_poll` et `cancel_event` (un `threading.Event`). Le délai d’attente débute après le retour de la soumission. Le client synchrone vérifie l’annulation et les échéances entre requêtes et rappels ; ces options ne peuvent interrompre un appel HTTP en cours.

`JobTimeoutError` et `JobCancelledError` conservent `job_id` et `last_response`. Reprenez avec `.wait(error.job_id)`. Le délai ou l’annulation locale n’annulent pas la tâche distante et les soumissions ne sont jamais répétées automatiquement. Ces outils n’ajoutent pas d’exécution en arrière-plan à la passerelle.

## "Contenu du package"

* Client `Phaseo`
* `chat.completions.create(...)` and `responses.create(...)` méthodes de compatibilité
* Des méthodes de ressources telles que `client.batches`, `client.videos`, `client.files`, and `client.async_jobs`
* Des méthodes pour créer les URL WebSocket des flux de cycle de vie des tâches asynchrones, des lots et des vidéos
* `client.batches.stream_results(batch_id)` pour les fragments d’octets JSONL des lots
* Des méthodes de cycle de vie des modèles telles que `get_model_deprecation_info(...)` and `validate_model(...)`
* Itérateurs de streaming pour le texte, les réponses et les messages
* Modèles de requête/réponse générés dans ~~phaseo.models~~


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