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.
Sommaire
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 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.
É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.
É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.
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.
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.
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.
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.
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.
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.
É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.
É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.
É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.
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.