Certains outils répondent immédiatement (de manière synchrone) ; d'autres lancent une tâche et la terminent en arrière-plan. Cette page traite du second cas : comment savoir qu'une tâche est terminée et comment récupérer le résultat.
La réponse à la création
Un outil asynchrone répond 202 :
{ "jobId": "...", "status": "...", "state": "pending", "requestId": "req_..." }
Le champ state est le même pour tous les outils - appuyez-vous dessus :
| Valeur | Signification |
|---|---|
pending | acceptée, pas encore démarrée |
running | en cours |
action_required | attend une action de votre part (vérification de rapport : confirmer les données extraites) |
completed | terminée |
partial | terminée en partie : certains fichiers ont échoué (possible pour le pack de contenu) |
failed | a échoué |
status est le statut brut de l'outil (DONE, processing, need_confirm, etc.). Il est conservé pour la compatibilité ; construisez les nouvelles intégrations sur state.
Identifiant de tâche
Chaque réponse concernant une tâche, quel que soit l'outil, contient le champ jobId : à la création, dans le statut et après la confirmation. Utilisez-le pour interroger le statut.
Avant la version 1.6.0, les outils renvoyaient l'identifiant sous différents noms (id, _id, contentGenJobId). Ces champs sont toujours renvoyés pour les intégrations existantes, mais ils sont obsolètes : utilisez jobId.
Interrogation
Le statut se trouve à l'adresse GET /<tool path>/jobs/{id} :
| Outil | Statut |
|---|---|
| Rapport d'évaluation complet | GET /valuation/report/jobs/{id} |
| Vérification de rapport | GET /valuation/review/jobs/{id} |
| Pack de contenu | GET /content/generate/jobs/{id} |
| Textes | GET /text/generate/jobs/{id} |
| Vidéo | GET /video/create/jobs/{id} |
| Avatar | GET /avatar/video/jobs/{id} |
| Photo | GET /photo/enhance/jobs/{id} |
| Plan d'étage | GET /floorplan/create/jobs/{id} |
GET /pdf/create/jobs/{id} |
- L'interrogation est gratuite et n'est pas comptée comme un appel d'API, mais elle compte dans la limite de débit. Une requête toutes les 3-5 secondes suffit.
- Seul le compte dont la clé a créé la tâche peut la voir. Un identifiant appartenant à quelqu'un d'autre ou inconnu renvoie le même
404. - Une clé d'agence liée à un agent ne voit que les tâches qu'elle a lancées ; la clé de l'agence entière voit toutes les tâches de l'agence.
- Une tâche peut être interrogée pendant 7 jours après sa création. Ensuite,
GET .../jobs/{id}répond404, et les fichiers du pack de contenu, des textes et des vidéos ne peuvent plus être téléchargés via l'API. - La réponse de statut contient les mêmes
statusetstate, ainsi que le résultat de l'outil dès qu'il est prêt. Une tâche de pack de contenu, de texte ou de vidéo en échec contienterror, une tâche photometadata.error- la raison sous forme de texte générique.
Le plan d'étage et la vérification de rapport traitent le document immédiatement : la réponse 202 contient déjà l'état final (completed, failed ou action_required), l'interrogation est donc facultative.
Quand une tâche attend votre action
Après la lecture du document, la vérification de rapport (Évaluation) s'arrête en action_required et renvoie les données extraites dans extracted. Vérifiez-les et confirmez :
curl -X POST https://developers.grem.capital/api/v1/valuation/review/jobs/JOB_ID/confirm \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-d '{}'
Un corps vide signifie « tout est correct ». Pour corriger une valeur, envoyez uniquement les champs modifiés dans extracted, sous les mêmes noms que dans la réponse (l'objet imbriqué subject est fusionné sur un niveau de profondeur). La tâche passe alors en running et le résultat arrive comme d'habitude.
Les webhooks à la place de l'interrogation
Chaque outil asynchrone envoie un événement <tool>.completed ou <tool>.failed (le pack de contenu envoie aussi content.partial). Abonnement et vérification de la signature : Webhooks.
- L'événement arrive généralement moins d'une minute après la fin de la tâche.
- Une tâche n'est suivie que si un abonnement à son événement existait déjà au moment de la création de la tâche. Abonnez-vous à l'avance, pas après avoir lancé la tâche.
- Si une tâche n'est pas terminée au bout de 30 minutes,
.failedarrive avecreason: "timeout". La tâche elle-même peut encore aboutir - l'interrogation montre son statut réel.
Fichiers prêts
Les fichiers se téléchargent via GET /artifacts/{path} avec la même clé (scope tools:artifacts). Gratuit, prend en charge Range. {path} est l'un des suivants :
| Quoi | Chemin |
|---|---|
| Un fichier de pack de contenu, de texte ou de vidéo | v1/ai/assistant/announcement/jobs/{jobId}/artifacts/{artifactId}/download |
| Vidéo avec avatar | v1/ai/assistant/avatar/jobs/{jobId}/artifacts/{artifactId}/download |
| Présentation PDF | v1/ai/pdf-generator/files/{id}/download |
| Photo améliorée | v1/ai/photo-enhancement/jobs/{jobId}/download/{variant} |
| PDF du rapport d'évaluation complet | v1/ai/appraisal/reports/{id}/pdf |
| PDF de l'estimation du loyer | v1/ai/appraisal/rent/{id}/pdf |
| Rapport de vérification | v1/ai/appraisal/reviews/{id}/report.pdf ou report.docx |
| Rapport de plan d'étage | v1/ai/floor-plan/jobs/{id}/report.pdf |
| Fichier de flyer | v1/ai/flyer/file/{name} |
| Piste vidéo (aperçu) | v1/ai/video-generator/music/{trackId} |
| Un fichier ordinaire | le chemin /files/... issu de la réponse de l'outil |
Les identifiants des fichiers du pack de contenu se trouvent dans le champ artifacts du statut de la tâche. Les fichiers du pack de contenu, des textes et des vidéos ne sont disponibles que pour les tâches créées via l'API par le même compte, pendant 7 jours.
curl -L -o video.mp4 \
"https://developers.grem.capital/api/v1/artifacts/v1/ai/assistant/announcement/jobs/JOB_ID/artifacts/ARTIFACT_ID/download" \
-H "Authorization: Bearer gsk_live_xxx"
Une présentation PDF possède aussi un champ link - l'adresse directe du document.
Voir aussi
- Outils via l'API - quels outils sont synchrones et lesquels sont asynchrones.
- Webhooks - recevoir les résultats sans interrogation.
- Fichiers - envoyer des images pour les annonces et les outils.