Часть инструментов отвечает сразу (синхронно), часть ставит задачу и завершает ее в фоне. Эта страница - о втором случае: как узнать, что задача готова, и как забрать результат.
Ответ на создание
Отложенный инструмент отвечает 202:
{ "jobId": "...", "status": "...", "state": "pending", "requestId": "req_..." }
Поле state одинаковое для всех инструментов, на него и ориентируйтесь:
| Значение | Что означает |
|---|---|
pending | задача принята, еще не началась |
running | выполняется |
action_required | ждет вас (проверка отчета: подтвердите извлеченные данные) |
completed | готово |
partial | готово частично: часть файлов не получилась (бывает у пакета контента) |
failed | не удалось |
Поле status - сырой статус конкретного инструмента (DONE, processing, need_confirm и т. п.). Оно оставлено для совместимости; новые интеграции стройте на state.
Идентификатор задачи
Каждый ответ задачи, от любого инструмента, содержит поле jobId: при создании, в статусе и после подтверждения. Опрашивайте статус именно по нему.
До версии 1.6.0 инструменты возвращали id под разными именами (id, _id, contentGenJobId). Эти поля оставлены для уже готовых интеграций, но устарели: используйте jobId.
Опрос
Статус живет по адресу GET /<путь инструмента>/jobs/{id}:
| Инструмент | Статус |
|---|---|
| Полный отчет об оценке | GET /valuation/report/jobs/{id} |
| Проверка отчета | GET /valuation/review/jobs/{id} |
| Пакет контента | GET /content/generate/jobs/{id} |
| Тексты | GET /text/generate/jobs/{id} |
| Видео | GET /video/create/jobs/{id} |
| Аватар | GET /avatar/video/jobs/{id} |
| Фото | GET /photo/enhance/jobs/{id} |
| Планировка | GET /floorplan/create/jobs/{id} |
GET /pdf/create/jobs/{id} |
- Опрос бесплатный и не считается вызовом API, но попадает под лимит частоты. Достаточно раз в 3-5 секунд.
- Задачу видит только тот аккаунт, чей ключ ее создал. Чужой или неизвестный id дает одинаковый
404. - Ключ агента агентства видит только задачи, которые запустил сам; ключ всего агентства видит все задачи агентства.
- Статус задачи можно запрашивать 7 дней после создания. Потом
GET .../jobs/{id}отвечает404, а файлы пакета контента, текстов и видео через API больше не скачать. - Ответ статуса содержит те же
statusиstateплюс результат инструмента, когда он готов. Задача пакета контента, текстов или видео со сбоем содержитerror, задача фото -metadata.error: причину общим текстом.
Планировка и проверка отчета обрабатывают документ сразу: ответ 202 уже содержит итоговое состояние (completed, failed или action_required), опрашивать не обязательно.
Когда задача ждет вас
Проверка отчета (Оценка) после чтения документа останавливается в состоянии action_required и отдает извлеченные данные в поле extracted. Проверьте их и подтвердите:
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 '{}'
Пустое тело означает «все верно». Чтобы исправить значение, передайте в extracted только измененные поля под теми же именами, что в ответе (вложенный объект subject сливается на один уровень вглубь). После этого задача переходит в running, а результат приходит как обычно.
Вебхуки вместо опроса
Каждый отложенный инструмент отправляет событие <инструмент>.completed или <инструмент>.failed (пакет контента еще и content.partial). Подписка и проверка подписи: Вебхуки.
- Событие приходит обычно в течение минуты после завершения задачи.
- Задача отслеживается, только если подписка на ее событие уже существовала в момент создания задачи. Подпишитесь заранее, а не после запуска.
- Если задача не завершилась за 30 минут, приходит
.failedсreason: "timeout". Сама задача при этом может еще завершиться - статус можно проверить опросом.
Готовые файлы
Файлы скачиваются через GET /artifacts/{path} тем же ключом (нужна область tools:artifacts). Запрос бесплатный, поддерживает Range. {path} - один из таких путей:
| Что | Путь |
|---|---|
| Файл пакета контента, текстов или видео | v1/ai/assistant/announcement/jobs/{jobId}/artifacts/{artifactId}/download |
| Видео с аватаром | v1/ai/assistant/avatar/jobs/{jobId}/artifacts/{artifactId}/download |
| PDF-презентация | v1/ai/pdf-generator/files/{id}/download |
| Улучшенное фото | v1/ai/photo-enhancement/jobs/{jobId}/download/{variant} |
| PDF полного отчета об оценке | v1/ai/appraisal/reports/{id}/pdf |
| PDF оценки аренды | v1/ai/appraisal/rent/{id}/pdf |
| Отчет проверки | v1/ai/appraisal/reviews/{id}/report.pdf или report.docx |
| Отчет планировки | v1/ai/floor-plan/jobs/{id}/report.pdf |
| Файл флаера | v1/ai/flyer/file/{name} |
| Трек для видео (прослушивание) | v1/ai/video-generator/music/{trackId} |
| Обычный файл | путь /files/... из ответа инструмента |
Идентификаторы файлов пакета контента лежат в поле artifacts статуса задачи. Файлы пакета контента, текстов и видео доступны только для задач, созданных через API тем же аккаунтом, в течение 7 дней.
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"
У PDF-презентации есть еще поле link - прямой адрес документа.
Связанные статьи
- Инструменты через API - какие инструменты синхронные, а какие отложенные.
- Вебхуки - получать результат без опроса.
- Файлы - загрузка изображений для объектов и инструментов.