Cet article se concentre sur les deux dernières catégories : Polling de TaskHandle pour les Tâches Asynchrones et les détails, pièges et différences entre les langues pour les réponses en flux de chat.
I. TaskHandle — Abstraction Unifiée des Tâches Asynchrones
Les trois SDK encapsulent les tâches asynchrones dansTaskHandle, offrant les mêmes 4 méthodes :
Deux Façons d’Appeler pour Créer une Tâche
Chaque ressource asynchrone (images.generate / video.generate / audio.generate) a un paramètre wait :
wait=False(par défaut) : Retourne immédiatementTaskHandle, le code métier décide quand interroger.wait=True: Le SDK appelle directementhandle.wait(), la fonction retourne la réponse après achèvement. Utilisez-le uniquement si vous êtes certain que l’API cible renverra toujours le champstatus: succeeded— quelques fournisseurs ne respectent pas cette convention, ce qui fera quewaittournera jusqu’àmax_waitavant de leverTimeoutError.
Différences d’Unités (⚠️ À Lire Absolument)
Les unités depoll_interval et max_wait sont différentes dans les trois langues, ce qui est un point de chute courant lors de la migration entre langues :
Prendre{ pollInterval: 3000 }de TS comme secondes et le traduire en Pythonpoll_interval=3000fera que le SDK attendra 50 minutes avant de faire la deuxième interrogation.
Exemple : Polling Explicite de Midjourney en Python
images.generate(..., wait=False)soumet lepromptà l’API Midjourney, obtient immédiatement lehandle, sans blocage.handle.wait(poll_interval=3.0, max_wait=180.0)envoie une requête POST à/midjourney/taskstoutes les 3 secondes, jusqu’à ce questatusdeviennesucceededoufailed, ou que le temps total dépasse 180 secondes, levantTimeoutError.- Une fois terminé,
result["response"]["data"]contient généralement 4 images (Midjourney par défaut 2x2 grid).
Exemple : Polling Explicite de TypeScript
Choix entre Génération Synchrone et Tâches Asynchrones
Si votre fournisseur génère des images de manière synchrone (NanoBanana / Flux / Seedream), ne passez paswait :
task_id + /tasks, c’est une génération synchrone ; le champ data de la réponse de génération synchrone contient déjà le résultat final.
Protocole Interne de TaskHandle
L’appel deTaskHandle.get() est :
response englobant — il lit directement le status de niveau supérieur, donc le passage entre les anciennes et nouvelles versions de réponse n’affecte pas le code métier.
II. Réponse en Flux SSE (chat.completions)
chat.completions.create(stream=True) est actuellement la seule interface en flux dans le SDK (le flux audio / vidéo n’est pas encore pris en charge). Les styles d’itération des trois langues sont natifs :
TypeScript
Python
Go
Structure des chunks en streaming
Chaque chunk est unchat.completion.chunk compatible avec OpenAI :
- Le premier chunk a généralement
delta.role: "assistant"maiscontentest vide. - Les chunks intermédiaires contiennent chacun
delta.content, qui peut être directement concaténé. - Le dernier chunk a
deltavide,finish_reasoneststop/length/content_filter.
Annulation en cours
L’annulation des tokens déjà facturés — les tokens générés avant le moment de l’annulation seront toujours facturés selon la consommation réelle.
Trois, délais et réessais
Les trois SDK partagent la même stratégie de réessai :
Pour désactiver les réessais : passer
max_retries=0 / maxRetries: 0 / WithMaxRetries(0) lors de la construction du client.
Le polling des tâches asynchrones (TaskHandle) n’est pas affecté par max_retries — sa boucle est de niveau métier et non de niveau HTTP, contrôlée par max_wait pour la durée totale.
Quatre, pièges courants
- Ne pas passer
waitaux fournisseurs synchrones : NanoBanana / Flux / Seedream sont tous générés de manière synchrone, forcerwait=Trueamènera le SDK à interroger une interfacetasksqui ne sera pas mise à jour. - Différences d’unités de TaskHandle : Python est en secondes, TS est en millisecondes, il est impératif de convertir lors du portage entre langages.
wait=Truepeut toujours provoquer unTimeoutError: La réponse doit satisfairestatus in ('succeeded','failed')pour sortir de la boucle ; si le fournisseur utilise d’autres noms de champs, le code métier doit lui-même analyserhandle.get().- Annulation en streaming : Les tokens générés avant l’annulation ont déjà été facturés.
- Réutiliser le client dans le même processus : Le SDK dispose d’un pool de connexions, créer fréquemment
new AceDataCloud()/AceDataCloud()peut rendre la poignée TLS un goulot d’étranglement.

