Usage de l'API V2 Yourtext Guru

Usage de l'API V2 Yourtext Guru

Documentation API Your Text Guru V2 - Le Guide pour Débutants
Bienvenue dans la documentation simplifiée de l'API Your Text Guru V2 ! Cette API vous permet d'automatiser et d'intégrer la puissance de Your Text Guru dans vos propres outils et flux de travail.
Ce guide se concentre sur les utilisations les plus courantes pour vous aider à démarrer rapidement.
URL de base de l'API : https://yourtext.guru/api/v2
Sommaire
3. Cas d'usage : Générer un guide et analyser un texte
Étape 1 : Générer un Guide
Étape 2 : Vérifier le statut du Guide
Étape 3 : Analyser votre texte
4. Cas d'usage : Générer un brief de contenu
Étape 1 : Lancer la génération du brief
Étape 2 : Récupérer le brief généré
5. Cas d'usage : Génération de contenu assistée par IA
5.1 Générer un texte complet (create)
5.2 Générer un texte simple (auto)
5.3 Générer un plan (outline)
5.4 Générer des questions (questions)
5.5 Reformuler un texte (rephrase)
6. Cas d'usage : Créer et utiliser un Maillage Thématique (Topical Mesh)
Étape 1 : Lancer la création du Maillage
Étape 2 : Vérifier le statut du Maillage
Étape 3 : Récupérer le Maillage
Étape 4 (Optionnel) : Obtenir le Wordcloud et les PAA du groupe

1. Authentification
Pour utiliser l'API, vous avez besoin de votre clé API personnelle, disponible sur votre page de configuration API.
Chaque requête doit inclure cette clé dans les en-têtes HTTP via l'une des deux méthodes suivantes :
Méthode 1 (Recommandée) : En-tête Authorization (Bearer Token)
Authorization: Bearer VOTRE_CLE_API
Méthode 2 : En-tête KEY
KEY: VOTRE_CLE_API
# Exemple cURL (Méthode 1) curl -X GET "https://yourtext.guru/api/v2/status" \ -H "Authorization: Bearer VOTRE_CLE_API" \ -i # Pour voir les en-têtes de réponse, y compris le Rate Limit
Remplacez VOTRE_CLE_API par votre clé réelle.
2. Concepts Clés
Guide : L'élément central. Un guide est généré pour une requête (mot-clé) et une langue spécifique. Il contient l'analyse sémantique (mots importants, n-grams, entités) basée sur les meilleurs résultats Google (ou Bing) pour cette requête.
Projet : Un conteneur pour organiser vos guides. Utile si vous gérez plusieurs sites ou clients.
Groupe : Un sous-conteneur optionnel au sein d'un projet pour regrouper des guides thématiquement liés (nécessaire pour le maillage thématique).
3. Cas d'usage : Générer un guide et analyser un texte
Le cœur de Your Text Guru : obtenir une analyse sémantique (le guide) pour une requête, puis vérifier si un texte est bien optimisé par rapport à ce guide.
Étape 1 : Générer un Guide
Endpoint : POST /guides
Paramètres (dans l'URL) :
query (obligatoire) : Votre mot-clé ou requête.
lang (obligatoire) : Le code langue (ex: fr_FR, en_US).
projectId (optionnel) : L'ID du projet.
groupId (optionnel) : L'ID du groupe.
type (optionnel) : google (défaut) ou bing.
Réponse (Succès 201 Created) : Infos du guide en cours (inProgress: true), notamment son id. Notez cet ID.
Important : La génération prend du temps. Respectez le Rate Limit.
# Exemple cURL pour créer un guide curl -X POST "https://yourtext.guru/api/v2/guides?query=meilleur%20VTT%20%C3%A9lectrique&lang=fr_FR" \ -H "Authorization: Bearer VOTRE_CLE_API"
# Exemple Python import requests, time api_key = 'VOTRE_CLE_API' query = 'meilleur VTT électrique' lang = 'fr_FR' base_url = 'https://yourtext.guru/api/v2' endpoint = '/guides' headers = {'Authorization': f'Bearer {api_key}'} params = {'query': query, 'lang': lang} try: response = requests.post(f"{base_url}{endpoint}", headers=headers, params=params) remaining = int(response.headers.get('x-ratelimit-remaining', 1)) print(f"Rate Limit restant: {remaining}") response.raise_for_status() if response.status_code == 201: guide_id = response.json()['id'] print(f"Guide créé avec ID : {guide_id}. Génération en cours…") if remaining <= 1: time.sleep(60) except requests.exceptions.RequestException as e: print(f"Erreur API: {e}")
Étape 2 : Vérifier le statut du Guide
Avant d'utiliser le guide, assurez-vous qu'il est prêt (ready: true).
Endpoint : GET /guides/{guideId}
Réponse : Détails du guide (ready, inProgress, error).
Important : Appelez cet endpoint périodiquement (ex : toutes les 30-60 secondes) en respectant le Rate Limit, jusqu'à ce que ready soit true.
# Exemple cURL pour vérifier le statut du guide ID 12345 GUIDE_ID=12345 curl -X GET "https://yourtext.guru/api/v2/guides/${GUIDE_ID}" \ -H "Authorization: Bearer VOTRE_CLE_API" \ -i
Étape 3 : Analyser votre texte
Une fois le guide prêt (ready: true), soumettez votre texte pour analyse.
Endpoint : POST /guides/{guideId}/check
Corps de la requête (JSON) : { "text": "Votre contenu…" }
Réponse (Succès 200 OK) : JSON avec SOSEO, DSEO, scores, areas.
Important : Respectez le Rate Limit.
# Exemple cURL pour analyser un texte GUIDE_ID=12345 TEXTE_A_ANALYSER="Voici mon superbe article…" curl -X POST "https://yourtext.guru/api/v2/guides/${GUIDE_ID}/check" \ -H "Authorization: Bearer VOTRE_CLE_API" \ -H "Content-Type: application/json" \ -d '{ "text": "'"${TEXTE_A_ANALYSER}"'" }' \ -i
4. Cas d'usage : Générer un brief de contenu
Utilisez un guide prêt et votre clé API OpenAI (configurée dans votre compte YTG) pour générer un brief.
Étape 1 : Lancer la génération du brief
Endpoint : POST /guides/{guideId}/brief
Prérequis : Guide prêt (ready: true), Clé OpenAI configurée dans YTG.
Réponse (Succès 200 OK) : Message indiquant le début de la génération (Guide brief start generation). C'est asynchrone.
Important : Respectez le Rate Limit.
# Exemple cURL pour lancer la génération du brief GUIDE_ID=12345 curl -X POST "https://yourtext.guru/api/v2/guides/${GUIDE_ID}/brief" \ -H "Authorization: Bearer VOTRE_CLE_API" \ -i
Étape 2 : Récupérer le brief généré
Endpoint : GET /guides/{guideId}/brief
Réponse (Succès 200 OK) : Le brief structuré en JSON.
Réponse (Erreur 400) : Si pas prêt (MessageGuideBriefInProgress) ou autre erreur.
Important : Attendez entre les appels et respectez le Rate Limit.
# Exemple cURL pour récupérer le brief GUIDE_ID=12345 curl -X GET "https://yourtext.guru/api/v2/guides/${GUIDE_ID}/brief" \ -H "Authorization: Bearer VOTRE_CLE_API" \ -i
5. Cas d'usage : Génération de contenu assistée par IA
Ces endpoints utilisent un guide prêt et votre clé OpenAI (configurée dans votre compte YTG) pour diverses tâches de génération. Respectez scrupuleusement le Rate Limit, car ces appels peuvent être coûteux.
5.1 Générer un texte complet (create)
Endpoint : POST /guides/{guideId}/seotxl/create
Corps de la requête (JSON) :
{ "text": "Optionnel : Texte de base ou instructions pour guider la génération.", "temperature": 1.0, // Optionnel : Créativité (0.1–1.9). Défaut ~1. "maxWords": 500 // Optionnel : Max mots (10–800). Défaut variable. }
Réponse (Succès 200 OK) : JSON avec le texte généré, lang, openAICost.
# Exemple cURL GUIDE_ID=12345 curl -X POST "https://yourtext.guru/api/v2/guides/${_GUIDE_ID}/seotxl/create" \ -H "Authorization: Bearer VOTRE_CLE_API" \ -H "Content-Type: application/json" \ -d '{ "temperature": 0.8, "maxWords": 600 }' \ -i
5.2 Générer un texte simple (auto)
Endpoint : POST /guides/{guideId}/seotxl/auto
Corps de la requête (JSON) : { "text": "Optionnel : Instructions ou contexte" }
Réponse (Succès 200 OK) : JSON avec content (texte généré), openAICost.
# Exemple cURL GUIDE_ID=12345 curl -X POST "https://yourtext.guru/api/v2/guides/${_GUIDE_ID}/seotxl/auto" \ -H "Authorization: Bearer VOTRE_CLE_API" \ -H "Content-Type: application/json" \ -d '{ "text": "Génère une introduction sur ce sujet." }' \ -i
5.3 Générer un plan (outline)
Endpoint : POST /guides/{guideId}/seotxl/outline
Réponse (Succès 200 OK) : JSON avec content (le plan), openAICost.
# Exemple cURL GUIDE_ID=12345 curl -X POST "https://yourtext.guru/api/v2/guides/${_GUIDE_ID}/seotxl/outline" \ -H "Authorization: Bearer VOTRE_CLE_API" \ -i
5.4 Générer des questions (questions)
Endpoint : POST /guides/{guideId}/seotxl/questions
Réponse (Succès 200 OK) : JSON avec content (les questions), openAICost.
# Exemple cURL GUIDE_ID=12345 curl -X POST "https://yourtext.guru/api/v2/guides/${_GUIDE_ID}/seotxl/questions" \ -H "Authorization: Bearer VOTRE_CLE_API" \ -i
5.5 Reformuler un texte (rephrase)
Endpoint : POST /guides/{guideId}/seotxl/rephrase
Corps de la requête (JSON) : { "text": "Le texte original à reformuler…" }
Réponse (Succès 200 OK) : JSON avec content (texte reformulé), openAICost.
# Exemple cURL GUIDE_ID=12345 TEXTE_ORIGINAL="Mon ancien texte peu optimisé." curl -X POST "https://yourtext.guru/api/v2/guides/${_GUIDE_ID}/seotxl/rephrase" \ -H "Authorization: Bearer VOTRE_CLE_API" \ -H "Content-Type: application/json" \ -d '{ "text": "'"${TEXTE_ORIGINAL}"'" }' \ -i
6. Cas d'usage : Créer et utiliser un Maillage Thématique (Topical Mesh)
Analyse les liens sémantiques potentiels entre les guides d'un même groupe pour suggérer un maillage interne.
Prérequis : Un Projet et un Groupe contenant plusieurs guides prêts (ready: true) dans la même langue.
Étape 1 : Lancer la création du Maillage
Endpoint : POST /projects/{projectId}/groups/{groupId}/topicalMesh
Réponse (Succès 200 OK) : Message confirmant le lancement ou la fin (Topical Mesh done).
Réponse (Erreur 400) : Si pas assez de guides (MessageGroupNotEnoughGuide), groupe trop grand (MessageGroupTooBig), etc.
Important : Respectez le Rate Limit. Le calcul peut prendre du temps pour les grands groupes.
# Exemple cURL PROJECT_ID=1 GROUP_ID=10 curl -X POST "https://yourtext.guru/api/v2/projects/${PROJECT_ID}/groups/${GROUP_ID}/topicalMesh" \ -H "Authorization: Bearer VOTRE_CLE_API" \ -i
Étape 2 : Vérifier le statut du Maillage
Contrairement à la génération de guide, il n'y a pas de statut "en cours" direct pour le maillage via cet endpoint. Cependant, vous pouvez vérifier l'état général du groupe.
Endpoint : GET /projects/{projectId}/groups/{groupId}
Réponse : Informations du groupe, dont topicalMeshStatus (NONE, IN_PROGRESS, READY).
Action : Appelez périodiquement (en respectant le Rate Limit) jusqu'à ce que topicalMeshStatus soit READY.
# Exemple cURL pour vérifier le statut du groupe PROJECT_ID=1 GROUP_ID=10 curl -X GET "https://yourtext.guru/api/v2/projects/${PROJECT_ID}/groups/${GROUP_ID}" \ -H "Authorization: Bearer VOTRE_CLE_API" \ -i
Étape 3 : Récupérer le Maillage
Une fois le statut READY, récupérez les suggestions de liens.
Endpoint : GET /projects/{projectId}/groups/{groupId}/topicalMesh
Réponse (Succès 200 OK) : JSON contenant topicalMesh, une liste d'objets avec :
source : Requête du guide source.
target : Requête du guide cible.
score : Force du lien sémantique suggéré (plus élevé = plus pertinent).
Réponse (Erreur 400) : Si le maillage n'est pas prêt (MessageGroupTopicalMeshNotReady) ou n'existe pas (MessageGroupNoTopicalMesh).
Important : Respectez le Rate Limit.
# Exemple cURL pour récupérer le maillage PROJECT_ID=1 GROUP_ID=10 curl -X GET "https://yourtext.guru/api/v2/projects/${PROJECT_ID}/groups/${GROUP_ID}/topicalMesh" \ -H "Authorization: Bearer VOTRE_CLE_API" \ -i
Étape 4 (Optionnel) : Obtenir le Wordcloud et les PAA du groupe
Une fois le maillage prêt (READY), vous pouvez aussi obtenir :
Wordcloud : GET /projects/{projectId}/groups/{groupId}/topicalMesh/wordcloud – Renvoie les termes les plus fréquents dans les guides du groupe.
PAA du Groupe : GET /projects/{projectId}/groups/{groupId}/topicalMesh/paa – Renvoie une compilation des questions "People Also Ask" trouvées dans les guides du groupe.
7. Gestion des Erreurs
Vérifiez toujours le code de statut HTTP. 200/201 = succès. 4xx = erreur client (votre requête, authentification, Rate Limit…). 5xx = erreur serveur.
En cas d'erreur 4xx/5xx, le corps JSON contient souvent message, code, key pour aider au diagnostic.
Gérez impérativement le code 429 Too Many Requests en faisant une pause.

    • Related Articles

    • Présentation de l'outil questions de yourtext.guru

      Découvrez quelles sont les questions que les internautes se posent. A partir d'une simple recherche, récupérez des listes entières de questions proches sémantiquement. La vidéo explicative des questions que l'on peut trouver dans l'outil de ...
    • Présentation de la fonctionnalité "entités" dans yourtext.guru

      La fonctionnalité "Entités" de yourtext.guru permet de trouver facilement les entités qui sont proches sémantiquement d'autres entités ou d'un contenu saisi par l'utilisateur. La vidéo explicative de la fonctionnalité "entités" - Comment fonctionne ...
    • Questions sur Yourtext Guru

      Voici une liste questions posées au support de Yourtext Guru et nos réponses : Quelle est la différence entre des jetons et token IA ? Les tokens IA permettent d'exploiter certaines fonctionnalités de Yourtext Guru. Historiquement, ils servaient ...
    • Comment changer son mot de passe yourtext.guru ?

      Découvrez la marche à suivre pour changer votre mot de passe dans l'outil yourtext.guru Pierre vous explique dans cette vidéo comment le faire. Il vous suffit de vous déconnecter de votre compte et cliquer sur "j'ai oublié mon mot de passe". Puis ...
    • Comment trouver des nouvelles idées de contenus avec yourtext.guru ?

      Trouver des nouvelles idées de contenus avec yourtext.guru. La vidéo explicative du générateur d'idées La vidéo en résumé : Le générateur d'idée est présent dans le dashboard de Yourtext Guru en cliquant sur le mot "idées" dans le menu déroulant sous ...