Usage de l'API V2 Yourtext Guru

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).

Étape 1 : Générer un Guide

Endpoint : POST /guides

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

É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.1 Générer un texte complet (create)

Endpoint : POST /guides/{guideId}/seotxl/create

{ "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

É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 :

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 :