Algunas herramientas responden al momento (de forma síncrona); otras lanzan un trabajo y lo terminan en segundo plano. Esta página trata el segundo caso: cómo saber que un trabajo ha terminado y cómo recoger el resultado.
La respuesta de creación
Una herramienta asíncrona responde 202:
{ "jobId": "...", "status": "...", "state": "pending", "requestId": "req_..." }
El campo state es igual para todas las herramientas; básese en él:
| Valor | Significado |
|---|---|
pending | aceptado, aún no iniciado |
running | en curso |
action_required | espera una acción suya (revisión de informe: confirmar los datos extraídos) |
completed | terminado |
partial | terminado en parte: algunos archivos fallaron (puede ocurrir con el paquete de contenido) |
failed | no ha funcionado |
status es el estado propio de la herramienta (DONE, processing, need_confirm, etc.). Se mantiene por compatibilidad; construya las integraciones nuevas sobre state.
Id del trabajo
Cada respuesta de un trabajo, de cualquier herramienta, lleva el campo jobId: al crearlo, en el estado y tras la confirmación. Consulte el estado con él.
Antes de la versión 1.6.0 las herramientas devolvían el id con nombres distintos (id, _id, contentGenJobId). Estos campos se mantienen para las integraciones existentes, pero están obsoletos: use jobId.
Consulta de estado
El estado está en GET /<ruta de la herramienta>/jobs/{id}:
| Herramienta | Estado |
|---|---|
| Informe de valoración completo | GET /valuation/report/jobs/{id} |
| Revisión de informe | GET /valuation/review/jobs/{id} |
| Paquete de contenido | GET /content/generate/jobs/{id} |
| Textos | GET /text/generate/jobs/{id} |
| Vídeo | GET /video/create/jobs/{id} |
| Avatar | GET /avatar/video/jobs/{id} |
| Foto | GET /photo/enhance/jobs/{id} |
| Plano | GET /floorplan/create/jobs/{id} |
GET /pdf/create/jobs/{id} |
- La consulta es gratuita y no cuenta como llamada a la API, pero sí cuenta para el límite de frecuencia. Basta con cada 3 a 5 segundos.
- Solo la cuenta cuya clave creó el trabajo puede verlo. Un id ajeno o desconocido devuelve el mismo
404. - Una clave de agente de una agencia ve solo los trabajos que lanzó ella misma; la clave de toda la agencia ve todos los trabajos de la agencia.
- Un trabajo se puede consultar durante 7 días desde su creación. Después
GET .../jobs/{id}responde404y los archivos del paquete de contenido, de textos y de vídeo ya no se pueden descargar por la API. - La respuesta de estado lleva los mismos
statusystate, más el resultado de la herramienta cuando está listo. Un trabajo fallido de paquete de contenido, textos o vídeo llevaerror, uno de fotosmetadata.error: el motivo como texto genérico.
El plano y la revisión de informe procesan el documento al momento: la respuesta 202 ya contiene el estado final (completed, failed o action_required), así que la consulta es opcional.
Cuando un trabajo espera por usted
Tras leer el documento, la revisión de informe (Valoración) se detiene en action_required y devuelve los datos extraídos en extracted. Revíselos y confirme:
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 cuerpo vacío significa «todo correcto». Para corregir un valor, envíe solo los campos cambiados dentro de extracted, con los mismos nombres que en la respuesta (el objeto anidado subject se fusiona un nivel). Después el trabajo pasa a running y el resultado llega como de costumbre.
Webhooks en lugar de consultas
Cada herramienta asíncrona envía un evento <herramienta>.completed o <herramienta>.failed (el paquete de contenido también content.partial). Suscripción y verificación de la firma: Webhooks.
- El evento suele llegar en el minuto siguiente al final del trabajo.
- Un trabajo se sigue solo si la suscripción a su evento ya existía cuando se creó el trabajo. Suscríbase antes, no después de lanzarlo.
- Si un trabajo no ha terminado en 30 minutos, llega
.failedconreason: "timeout". El trabajo aún puede terminar: la consulta muestra su estado real.
Archivos listos
Los archivos se descargan con GET /artifacts/{path} y la misma clave (ámbito tools:artifacts). Gratis, admite Range. {path} es uno de estos:
| Qué | Ruta |
|---|---|
| Archivo del paquete de contenido, de textos o de vídeo | v1/ai/assistant/announcement/jobs/{jobId}/artifacts/{artifactId}/download |
| Vídeo con avatar | v1/ai/assistant/avatar/jobs/{jobId}/artifacts/{artifactId}/download |
| Presentación en PDF | v1/ai/pdf-generator/files/{id}/download |
| Foto mejorada | v1/ai/photo-enhancement/jobs/{jobId}/download/{variant} |
| PDF del informe de valoración completo | v1/ai/appraisal/reports/{id}/pdf |
| PDF de la estimación del alquiler | v1/ai/appraisal/rent/{id}/pdf |
| Informe de revisión | v1/ai/appraisal/reviews/{id}/report.pdf o report.docx |
| Informe del plano | v1/ai/floor-plan/jobs/{id}/report.pdf |
| Archivo del folleto | v1/ai/flyer/file/{name} |
| Pista para vídeo (escucha) | v1/ai/video-generator/music/{trackId} |
| Archivo normal | la ruta /files/... de la respuesta de la herramienta |
Los ids de los archivos del paquete de contenido están en el campo artifacts del estado del trabajo. Los archivos del paquete de contenido, de textos y de vídeo solo están disponibles para trabajos creados por API con la misma cuenta, durante 7 días.
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"
La presentación en PDF tiene además un campo link: la dirección directa del documento.
Artículos relacionados
- Herramientas por API: cuáles son síncronas y cuáles asíncronas.
- Webhooks: recibir resultados sin consultar.
- Archivos: subir imágenes para inmuebles y herramientas.