Guides essentiels
Journaux et dépannage
Conservez les identifiants nécessaires pour suivre les requêtes, les tâches et les facturations
Conservez les identifiants de requête, de tâche et de facturation TokenLab dans vos journaux. Ils permettent de relier une action utilisateur à son résultat et à sa facturation sans stocker le prompt ou les médias privés.
Dans la Console, les détails des requêtes et des réponses capturés sont disponibles pendant 30 jours à compter de leur capture, l'accès prenant fin à l'expiration exacte, même si le nettoyage physique est toujours en file d'attente. L'identité de la requête et l'historique de facturation/utilisation ont des durées de vie indépendantes. Voir Rétention des données.
D'une requête à une investigation et au support
-
Ouvrez Runs dans l'espace de travail propriétaire de la requête. Trouvez son Request ID et sélectionnez la ligne correspondante.
-
Choisissez Open full details pour accéder à une page dédiée. Back to requests permet de restaurer les filtres de la liste. Un lien n'accorde jamais l'accès à un autre espace de travail ; utilisez un compte autorisé pour cet espace de travail.
-
Pour un statut en attente ou inconnu, actualisez d'abord la progression. En cas d'échec ou de réponse interrompue, choisissez Investigate the issue lorsque cela est disponible. Cela lance une investigation pour cette requête dans l'Agent intégré ; cela ne rejoue pas la requête originale du modèle. Les requêtes réussies ne nécessitent pas d'investigation par défaut.
-
Si vous avez toujours besoin d'aide, choisissez l'action de support humain depuis la requête ou l'investigation. Cela ouvre un aperçu avec la requête et la conversation liées, si disponibles. Examinez le résumé et supprimez le contenu privé, puis sélectionnez explicitement Submit. Une investigation ou un aperçu seul n'envoie pas de demande de support.
-
Après la soumission, conservez la confirmation et poursuivez la même conversation dans Support. Réutilisez-la pour les réponses et les informations supplémentaires au lieu de soumettre des doublons.
Identifiants à conserver
| Identifiant | Où il apparaît | Utilisation |
|---|---|---|
request_id | Corps d'erreur, journaux du tableau de bord, enregistrements d'utilisation | Support au niveau de la requête et rapprochement |
id / task_id | Réponses de création asynchrone et de statut | Interrogation de tout travail asynchrone avec GET /v1/tasks/{id} |
poll_url | Réponses de création asynchrone | URL de statut ; interrogez /v1/tasks/{id} avec id |
billing_transaction_id | Réponses non-streaming une fois réglées, réponses de statut de tâche asynchrone, enregistrements d'utilisation, X-Billing-Transaction-ID | Rapprochement des coûts |
X-Task-ID | En-têtes de réponse de tâche asynchrone | Corrélation de tâche au niveau de l'en-tête |
| Votre propre ID de travail/utilisateur | Votre application | Trouver la requête TokenLab pour une action utilisateur |
Les enregistrements destinés aux clients doivent utiliser les identifiants TokenLab. N'exposez jamais d'URL de service privées, de clés de cache ou de métadonnées de diagnostic.
Ce qu'il faut journaliser
Journalisez suffisamment d'informations pour diagnostiquer la requête sans divulguer de secrets :
- Point de terminaison, méthode HTTP, modèle, code de statut, horodatage et latence.
- Identifiants publics :
request_id,task_id,poll_urletbilling_transaction_idlorsqu'ils sont présents. - Noms des champs envoyés dans la requête, et non le prompt complet ou le contenu média privé.
- Réponses finales de statut asynchrone et champs d'erreur sécurisés.
- Nombre de tentatives du client et si la tentative a créé une nouvelle tâche ou repris une tâche existante.
Redigez toujours Authorization, les clés API, les jetons de gestion, les URL signées, les URL de médias privés, les prompts complets et les données personnelles des utilisateurs, sauf si vous avez une autorisation explicite pour les conserver.
Matrice de dépannage
| Symptôme | Première vérification | Page utile |
|---|---|---|
401 ou 403 | Clé API, jeton de gestion, accès à l'organisation, portée de la clé | Authentification |
402 | Solde, limite de dépenses de la clé API | Facturation & Tarification |
429 | Niveau de compte, limite de débit du point de terminaison, comportement de nouvelle tentative | Limites de débit |
400 invalid_request_error | Champ non pris en charge, mauvais point de terminaison, champ requis manquant ou inadéquation de la requête du modèle | Gestion des erreurs |
| Tâche asynchrone introuvable | Mauvaise clé API, ID mal saisi ou tâche expirée | Travaux asynchrones & Interrogation |
| Le coût ne correspond pas à l'UI | Moment du règlement ou comparaison du mauvais identifiant | Facturation & Tarification |
Rapprochement de l'utilisation
Utilisez l'API de gestion pour le rapprochement côté serveur :
curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=video" \
-H "Authorization: Bearer mt-your-management-token"GET /v1/management/api-keys/{keyId}/usage peut filtrer par scene, model, modelVendor, startDate et endDate. Utilisez ces enregistrements plutôt que de scraper les pages de la Console ou de calculer les frais uniquement à partir du nombre de jetons de réponse. Une endDate sans heure signifie 00:00 UTC au début de ce jour ; voir Obtenir l'utilisation de la clé API.
Les réponses en streaming peuvent être réglées après l'envoi du flux, de sorte qu'un en-tête de facturation peut être absent même si l'utilisation est enregistrée ultérieurement. Les tâches média asynchrones peuvent être réglées après l'interrogation terminale.
Ce qu'il faut envoyer au support
Lorsque vous contactez le support, incluez :
request_id.task_idetpoll_urlpour le travail asynchrone.billing_transaction_idlorsqu'il est présent.- Point de terminaison, méthode, modèle, horodatage et code de statut.
- Noms des champs de la requête et le corps d'erreur sécurisé.
- Votre résultat attendu et ce que l'utilisateur a réellement vu.
N'incluez pas de clés API, de jetons de gestion, de médias privés, de prompts complets, d'URL de service privées ou d'identifiants de diagnostic. Si le support a besoin d'un exemple de requête, envoyez une copie expurgée.
Vérifications à automatiser
- Alertez séparément sur les réponses répétées
401,402,429et5xx; chacune nécessite une réponse différente. - Suivez les travaux asynchrones qui restent non terminaux au-delà de votre SLA produit.
- Suivez les tentatives de création en double pour le même ID de travail utilisateur.
- Échantillonnez les travaux terminés et vérifiez que l'actif visible par l'utilisateur, l'enregistrement d'utilisation et l'enregistrement de tâche stocké concordent.
Référence API
| Sujet | Référence |
|---|---|
| Gestion des erreurs | Gestion des erreurs |
| Limites de débit | Limites de débit |
| Facturation & Tarification | Facturation & Tarification |
| Obtenir l'utilisation de la clé API | Obtenir l'utilisation de la clé API |
| Obtenir le statut de la tâche | Obtenir le statut de la tâche |