|

Documentation de recherche du Request ID d’APIYI mise à niveau et optimisée : deux méthodes pour l’obtenir, via le texte d’erreur original et via les en-têtes de réponse

Documentation de recherche du Request ID d’APIYI mise à niveau et optimisée : deux méthodes pour l’obtenir, via le texte d’erreur original et via les en-têtes de réponse

Note de l’auteur : la documentation de recherche du Request ID d’APIYI a été mise à jour. Cet article explique clairement quelle chaîne copier en cas d’erreur, quels ID sont inutilisables, comment conserver le task_id d’une vidéo asynchrone, et quels éléments fournir quand les logs ne contiennent aucune trace.

Quand une invocation échoue et qu’on ouvre un ticket, les développeurs butent souvent sur le même point : ils ont bien une chaîne d’ID en main, mais le support ne la retrouve pas dans les logs. La cause habituelle, c’est qu’ils ont copié le X-Request-Id de l’usine upstream, et non le X-Shellapi-Request-Id propre à APIYI. La nouvelle documentation a justement été réécrite pour régler ce problème ; elle se trouve à l’adresse docs.apiyi.com/faq/request-id-troubleshooting.

Il ne s’agit pas d’un simple ravalement de façade de la documentation. L’ancienne version partait des « en-têtes de réponse », avec des « généralement » et des « éventuellement » à chaque phrase : à la fin, on ne savait toujours pas où copier. La nouvelle version inverse l’ordre : d’abord la réponse, ensuite la méthode pour l’obtenir, et enfin le modèle de ticket.

Ce que vous y gagnez : après lecture, vous récupérez le bon Request ID en 10 secondes, et vous savez reconnaître les ID erronés. Si aucune trace n’apparaît dans les logs, vous saurez aussi quels éléments compléter.

apiyi-request-id-docs-upgrade-fr-image-0


Ce qui a changé dans la doc Request ID d’APIYI

La première phrase de la nouvelle version donne directement la réponse : le Request ID d’APIYI, c’est le X-Shellapi-Request-Id présent dans les en-têtes de réponse, et en cas d’erreur, la même valeur apparaît aussi à la fin du message. Au passage, on a corrigé plusieurs formulations de l’ancienne page qui présentaient x-request-id comme un simple « notez-le pour faciliter le diagnostic ».

Information Détail
Date de mise à jour 2026-11-16
Emplacement de la doc Nouvelle page « Diagnostic via Request ID » dans la rubrique FAQ
Réponse principale Request ID = en-tête de réponse X-Shellapi-Request-Id ; le (request id: ...) en fin de message d’erreur correspond à la même valeur
Nouveautés 2 façons de l’obtenir, tableau de correspondance des ID, logs de la console qui ne l’affichent pas, explications sur la vidéo asynchrone, que faire si on ne le trouve pas, modèle de ticket
Note de sécurité Le Request ID n’est pas une clé : on peut le coller dans un ticket, un chat ou une capture d’écran ; ce qu’il ne faut jamais diffuser, c’est la clé API complète commençant par sk-
Public concerné Tous les développeurs qui appellent chez APIYI les interfaces texte, image, Embedding, Claude Messages, Responses et vidéo asynchrone

Comme le précise la doc, le nom de cet en-tête n’est pas sensible à la casse. Il est renvoyé aussi bien pour les requêtes réussies que pour les erreurs métier et les requêtes en streaming — dans ce cas, l’en-tête de réponse arrive avant le premier bloc de données. Les interfaces vidéo asynchrones le renvoient également, à la soumission comme à la consultation.


Request ID d’APIYI : quelle chaîne copier maintenant ? Deux chemins

Commencez par reconnaître le format : le Request ID d’APIYI commence par un horodatage UTC de 14 chiffres. Par exemple, 2026111602224568279882196e93ae3kTS58ypN : les 14 premiers chiffres 20261116022245 correspondent à 2026-11-16 02:22:45 UTC, soit 10:22:45 heure de Pékin. Comparez ce préfixe avec l’heure de votre appel : vous saurez en gros si vous avez copié le bon identifiant.

apiyi-request-id-docs-upgrade-fr-image-1

Chemin 1 : copier directement depuis le JSON d’erreur

Cette méthode convient à la plupart des utilisateurs de clients. En cas d’erreur, la fin du champ message du JSON d’erreur contient un segment (request id: ...) ; il suffit de copier intégralement la chaîne entre parenthèses.

  1. Recherchez le JSON d’erreur complet dans le client ou dans les logs.
  2. Repérez la fin du champ message.
  3. Copiez toute la chaîne de caractères qui suit request id: sans la tronquer.

Journaux de la console : ils confirment l’appel, mais n’affichent pas le Request ID

Beaucoup de gens ont d’abord le réflexe d’aller chercher l’ID dans la page « Journaux » de la console. La nouvelle documentation y consacre une section entière : la page des journaux n’affiche pas X-Shellapi-Request-Id et ne propose aucun champ pour le rechercher.

Dans les journaux, on voit l’horodatage, le modèle, le nom du jeton, le mode streaming ou non, la durée, le statut, les tokens d’entrée/sortie, le coût, le groupe, le multiplicateur et l’IP. Cela suffit pour confirmer si cet appel a bien atteint APIYI, quel modèle a été utilisé et combien cela a coûté, mais cela ne permet pas de localiser le problème lors d’un signalement.

Lors d’un signalement, l’ID ne peut donc venir que de deux sources : le message d’erreur d’origine (chemin 1) et les en-têtes de réponse (chemin 2). Les journaux servent à compléter les informations sur l’heure, le modèle, le jeton et le coût.

Chemin 2 : lire les en-têtes de réponse dans le code

Lorsque vous collectez automatiquement les erreurs, il est conseillé d’enregistrer directement cet en-tête dans le code. Pour toutes les méthodes, l’URL de base doit être https://api.apiyi.com/v1.

  1. cURL : ajoutez curl -D headers.txt pour écrire les en-têtes de réponse dans un fichier, puis recherchez x-shellapi-request-id dans ce fichier. Pour un diagnostic ponctuel, vous pouvez aussi utiliser curl -i pour les afficher directement.
  2. Python requests : une fois l’objet réponse obtenu, lisez r.headers.get("x-shellapi-request-id"). Vous pouvez le lire aussi bien en cas de succès qu’en cas d’erreur.
  3. SDK OpenAI (Python) : dans une valeur de retour standard, _request_id correspond à x-request-id, qui est généralement vide sur APIYI. La bonne méthode consiste à utiliser plutôt client.chat.completions.with_raw_response.create(...), à lire raw.headers.get("x-shellapi-request-id"), puis à récupérer le résultat avec raw.parse(). En cas d’erreur, lisez e.response.headers dans except openai.APIStatusError as e.
  4. Node.js : avec fetch, lisez res.headers.get("x-shellapi-request-id").
  5. Postman : après avoir envoyé la requête, ouvrez l’onglet Headers de la section de réponse et cherchez X-Shellapi-Request-Id.
  6. Front-end navigateur : les appels cross-origin sont soumis aux restrictions CORS, et JS ne peut pas lire cet en-tête. Vous pouvez l’enregistrer dans un proxy backend, ou le consulter dans les outils de développement, sous Network → la requête concernée → Response Headers.

🚀 Prise en main rapide : pour vérifier que votre code parvient bien à lire cet en-tête, vous pouvez envoyer une requête minimale avec un jeton APIYI (apiyi.com) et regarder si un ID commençant par un horodatage à 14 chiffres s’affiche. Cette étape consomme quelques tokens ; il est conseillé de choisir une invite produisant une sortie très courte.


Quels ID ne sont pas des Request ID APIYI

Une même réponse peut contenir plusieurs « ID » différents, et c’est précisément là que beaucoup de tickets restent bloqués. La nouvelle version de la documentation propose un tableau comparatif ; voici l’essentiel.

apiyi-request-id-docs-upgrade-fr-image-2

Champ Source Utilisable pour signaler un incident et consulter les logs Signe distinctif
X-Shellapi-Request-Id APIYI ✅ C’est bien celui-là Commence par une date UTC sur 14 caractères
X-Oneapi-Request-Id Couche intermédiaire ❌ Nom d’en-tête différent
X-Request-Id Fournisseur d’origine en amont ❌ Introuvable dans les logs APIYI Souvent précédé de req_ ou au format UUID
Autres en-têtes personnalisés du canal Canal ❌ Noms d’en-tête variés
id du corps de réponse Completion ID / Response ID ❌ Précédé de chatcmpl-, resp_
generation_id d’image Résultat de génération d’images ❌ Se trouve dans le corps de réponse
task_id Tâche asynchrone ❌ Ce n’est pas un Request ID, mais il faut le fournir en même temps Consulter la tâche, vérifier la facturation

La règle est simple : si l’ID ne commence pas par une date sur 14 caractères, ce n’est pas un Request ID APIYI. Si vous recevez un ID commençant par req_, il est possible que la requête ait été envoyée directement à OpenAI. Dans ce cas, vérifiez d’abord si la Base URL est bien https://api.apiyi.com/v1.


Comment stocker séparément le task_id et le Request ID des vidéos asynchrones

Une vidéo asynchrone passe par deux étapes, « soumission » et « consultation ». Chacune renvoie un nouveau X-Shellapi-Request-Id, et il y a en plus un ID de tâche : on finit vite par tout mélanger. La nouvelle doc recommande de stocker séparément le Request ID de la requête de soumission et le task_id utilisé pour le polling.

Modèle Emplacement du task_id Endpoint de consultation Champ à ne pas confondre
Seedance id à la racine du corps de réponse (le champ ne s’appelle pas task_id) GET /seedance/api/v3/contents/generations/tasks/{id} —
Wan / HappyHorse output.task_id GET /v1/tasks/{task_id} Le request_id du corps de réponse vient de l’upstream, ce n’est pas celui des logs APIYI

En pratique, pour chaque tâche, je vous conseille de stocker 3 champs : le X-Shellapi-Request-Id au moment de la soumission, le task_id et l’heure de soumission. Le Request ID renvoyé lors de la consultation de la tâche peut être enregistré si besoin. En cas d’échec de soumission, utilisez le Request ID pour ouvrir un ticket d’assistance ; si la tâche est bloquée ou si vous avez un doute sur la facturation, le task_id sert à la fois à consulter la tâche et à vérifier la facturation.


Que fournir lorsque le Request ID est introuvable dans les logs

Même avec l’ID en main, il n’est pas garanti de le retrouver dans les logs. La nouvelle documentation consacre une section à part au cas « pas de Request ID dans les logs de la console » ; les autres situations où l’ID reste introuvable se traitent par analogie.

Situation Cause À fournir en complément
La requête échoue avant de recevoir une réponse DNS, TCP/TLS, refus du proxy, timeout côté client : aucune en-tête de réponse n’a été reçue Le message d’erreur brut, l’heure de l’appel, une description de l’environnement réseau
Le client affiche seulement « échec de la requête » Le client ne remonte pas l’erreur brute Récupérer l’ID via la voie 1 ou la voie 2 ; les logs permettent uniquement de confirmer si l’appel a atteint le service
L’ID commence par req_ La requête a peut-être atteint OpenAI directement Vérifier l’URL de base (Base URL), puis réessayer
Introuvable même dans les logs Au-delà de la période de rétention, ou mauvais ID Vérifier le format de l’ID ; les logs ne conservent que le mois en cours et les deux mois civils précédents

Autre point : la page de la console n’affiche pas l’ID, mais l’API de consultation des logs permet de rechercher par request_id. Le tableau ci-dessous vient d’une vérification effectuée sur un appel réel du 2026-11-16, avec les modèles deepseek-flash et gpt-image-2, la requête étant envoyée vers https://api.apiyi.com/v1.

Appel Statut HTTP En-têtes de réponse Résultat de la recherche par request_id dans les logs
deepseek-flash, non-streaming 200 Présence de x-shellapi-request-id, absence de x-request-id 1 enregistrement de consommation retrouvé précisément
deepseek-flash, streaming 200 Présent, lisible avant le premier bloc data: —
gpt-image-2, size=999×999 400 Même valeur que le request id en fin de message 3 lignes d’erreur/retry, aucune ligne de consommation
Nom de modèle inexistant 503 Même valeur que le request id en fin de message Aucune ligne trouvée

En résumé : la page de logs de la console n’affiche pas le Request ID, mais l’API de consultation des logs permet de retrouver les « lignes de consommation » et les « lignes d’erreur » via request_id — sans garantie qu’il en existe à chaque fois. Une requête qui a atteint le canal puis échoué côté canal (par exemple une erreur de paramètre) laisse une ligne d’erreur. Une requête rejetée séance tenante au niveau de la passerelle (par exemple aucun canal disponible) peut ne laisser aucune ligne. Si la recherche ne donne rien, complétez le dossier avec l’ID présent dans les en-têtes de réponse ou dans le message d’erreur brut, plus l’heure de l’appel.

Si le support a besoin d’une reproduction, vous pouvez refaire un appel sur APIYI apiyi.com avec le même jeton et les mêmes paramètres, ou changer de modèle pour vérifier s’il s’agit de la même erreur. Une reproduction consomme aussi des tokens : pensez à noter le Request ID de chaque tentative.

🎯 Conseil de diagnostic : lorsque vous reproduisez l’erreur, fixez l’URL de base sur https://api.apiyi.com/v1 et notez à chaque fois X-Shellapi-Request-Id ainsi que l’heure de l’appel. Transmettez ensuite l’ID et l’heure au support, qui pourra rechercher par ID côté back-end et déterminer plus rapidement si l’erreur s’est produite au niveau de la passerelle ou du canal.


Modèle de ticket d’erreur Request ID pour APIYI

Copiez simplement les champs ci-dessous dans le ticket :

  • Request ID : la chaîne qui commence par un horodatage de 14 chiffres
  • Modèle : par ex. gpt-image-2
  • Endpoint : par ex. POST /v1/chat/completions
  • Date et heure : avec fuseau horaire, par ex. 2026-11-16 11:24:04 UTC+8
  • Statut HTTP : par ex. 400 / 503
  • Message d’erreur : collez l’erreur complète, avec (request id: ...)
  • Déjà tenté : par ex. changement de modèle, vérification du Base URL, 2 nouvelles tentatives
  • task_id (uniquement pour les vidéos asynchrones) : ID de tâche renvoyé à la soumission

Deux points d’attention : n’envoyez pas votre clé API complète ; si le corps de la requête ou les images contiennent des informations privées, masquez-les avant de les transmettre.


Impact de la mise à jour de la documentation Request ID sur les développeurs

Impact pour les développeurs

  • Un aller-retour de moins pour signaler un problème : en donnant le bon ID dès le premier message, le support n’a plus à revenir poser des questions.
  • Les utilisateurs de SDK ne récupèrent plus de valeur vide : le piège lié à _request_id et la façon de récupérer la valeur avec with_raw_response sont désormais expliqués.
  • Les tâches vidéo deviennent traçables : le Request ID et l’ID de tâche sont stockés séparément, ce qui permet de retrouver une tâche et de vérifier la facturation.

À garder en tête avec l’ancienne documentation

Sur certaines pages de capacités d’endpoint, pages d’actualités et pages de journalisation des erreurs, x-request-id est encore présenté comme un élément « à noter pour faciliter le diagnostic ». Si vous rencontrez ce type de formulation, la nouvelle page Request ID fait référence. Dans les modèles de code, remplacez également x-request-id par x-shellapi-request-id.


Questions fréquentes (FAQ)

Q1 : Quel est exactement le Request ID d’APIYI ?

C’est le X-Shellapi-Request-Id présent dans les en-têtes de réponse, qui commence par un horodatage UTC à 14 chiffres. En cas d’erreur, la valeur à la fin du message d’erreur, `(request id: …)`, est identique.

Q2 : Est-il sûr de partager un Request ID avec quelqu’un ?

Oui, sans danger. Comme le précise la documentation, le Request ID n’est pas une clé : vous pouvez le coller dans un ticket, une conversation ou une capture d’écran. Ce qu’il ne faut jamais divulguer, c’est la clé API complète commençant par `sk-`.

Q3 : Pourquoi l’ID lu par le SDK OpenAI est-il vide ?

Par défaut, le `_request_id` du SDK lit x-request-id. Il suffit d’utiliser `with_raw_response`, ou de récupérer x-shellapi-request-id depuis les en-têtes de réponse de `APIStatusError`.

Q4 : Comment vérifier rapidement que je récupère bien le bon Request ID ?

1. Créez un compte sur APIYI (apiyi.com) et obtenez une clé API ; les nouveaux utilisateurs disposent d’un quota de test gratuit.
2. Définissez le Base URL sur `https://api.apiyi.com/v1` et envoyez une requête minimale.
3. Affichez x-shellapi-request-id et vérifiez que vous obtenez bien cette chaîne à chaque appel ; la page des logs permet seulement de contrôler si cet appel est arrivé et s’il a été facturé, elle n’affiche pas l’ID.

Q5 : Peut-on encore retrouver une erreur d’il y a trois mois ?

En général, non. Les logs sont conservés pour le mois en cours et les deux mois civils précédents ; pour les enregistrements plus anciens, il faut s’appuyer sur le Request ID et le message d’erreur d’origine que vous avez sauvegardés.


APIYI Request ID : les points clés à retenir

  • Le seul ID valable : X-Shellapi-Request-Id, qui commence par un horodatage UTC à 14 chiffres
  • Deux façons de l’obtenir : copier le message d’erreur, ou lire l’en-tête de réponse dans le code (les journaux ne font que confirmer l’appel, ils n’affichent pas l’ID)
  • Les erreurs fréquentes : X-Request-Id, req_, chatcmpl-, resp_ ou un UUID — aucun de ceux-là ne sert à signaler un incident
  • Pour la vidéo, gardez deux identifiants : conservez séparément le Request ID de la soumission et l’ID de la tâche
  • Les journaux ne sont pas infaillibles : la page de la console n’affiche pas l’ID ; une requête rejetée sur-le-champ par la passerelle peut même ne laisser aucune trace — dans ce cas, joignez le texte d’erreur et l’horodatage
  • Vérification rapide : envoyez une requête minimale sur APIYI apiyi.com et vous verrez tout de suite si cet en-tête est lisible

En résumé

La mise à jour de la documentation sur la recherche du Request ID chez APIYI tient en trois points :

  1. La réponse en premier : le Request ID, c’est X-Shellapi-Request-Id, et la même valeur figure à la fin du message d’erreur.
  2. Écarter les mauvais ID : un tableau comparatif clarifie la différence entre les identifiants de la couche intermédiaire, de l’upstream, du corps de réponse et de la tâche.
  3. Un plan si l’on ne trouve rien : pour chacune des quatre situations, les pièces à fournir, avec un modèle de ticket directement réutilisable.

Mon conseil : modifiez dès maintenant le champ de journalisation des erreurs dans votre code pour y mettre x-shellapi-request-id. Ensuite, si un problème survient, transmettez l’ID et l’heure de l’appel au support : l’équipe backend retrouvera l’appel par l’ID, et vous pourrez ouvrir un ticket avec tous les éléments.


📚 Références

  1. Documentation de dépannage Request ID APIYI (nouvelle version) : la base factuelle de cet article
  2. Lien : docs.apiyi.com/faq/request-id-troubleshooting
  3. Description : détaille les deux méthodes de récupération, l’explication des journaux de la console, le tableau de correspondance des ID, les précisions sur la vidéo asynchrone et le modèle de ticket

  4. Durée de conservation des journaux : explication de la période de rétention

  5. Lien : docs.apiyi.com/faq/log-retention-policy
  6. Description : permet de vérifier si les enregistrements d’erreur sont encore consultables

Auteur : équipe technique APIYI
Échanges techniques : n’hésitez pas à nous contacter depuis la page d’accueil du site APIYI apiyi.com ; joindre l’en-tête X-Shellapi-Request-Id lors de la soumission d’un ticket accélère le traitement

Publications similaires