Завдання і результати

Останнє оновлення: 2026-10-034 хв читання

Частина інструментів відповідає одразу (синхронно), частина ставить завдання і завершує його у фоні. Ця сторінка - про другий випадок: як дізнатися, що завдання готове, і як забрати результат.

Відповідь на створення

Відкладений інструмент відповідає 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}`
PDF	`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 - які інструменти синхронні, а які відкладені.
Вебхуки - отримувати результат без опитування.
Файли - завантаження зображень для об'єктів і інструментів.

Ця стаття була корисною?