Skip to main content
Используйте Agent API, чтобы ставить задачи Krea Agent из собственного приложения. В запросах и ответах используются JSON-поля в camelCase. Агент работает в фоновом режиме, а ваше приложение читает его прогресс и результаты.
Агент работает в фоновом режиме. Он не задаёт вопросов, а запросы на подтверждение стоимости и разрешений одобряются автоматически. Укажите в промпте все требования и ограничения. Проверьте задачу перед отправкой.

Аутентификация, доступ и биллинг

Передавайте Authorization: Bearer KREA_API_KEY в каждом запросе к https://api.krea.ai. Персональные, сервисные и устаревшие API-ключи используют стандартную аутентификацию публичного API. Читать и продолжать можно только сессии, принадлежащие аутентифицированному пользователю в аутентифицированном рабочем пространстве. Знание ID сессии не даёт к ней доступа. Вложения из Krea Files также должны быть доступны этому пользователю в этом рабочем пространстве.
Ходы агента расходуют баланс compute-юнитов рабочего пространства. API-баланс они не используют. Права тарифа Agent и лимиты сообщений тарифа Free по-прежнему действуют. См. Тарифы, доступ и кредиты Agent.
Каждый ответ содержит url, по которому можно открыть сессию в приложении Krea при наличии соответствующего доступа к аккаунту и рабочему пространству.

Запуск сессии и ожидание результата

Сначала задайте KREA_API_KEY в переменных окружения. Выберите Bash с curl и jq, Python с requests или Node.js со встроенным fetch либо Krea SDK.
1

Отправьте первый ход

Не указывайте sessionId, чтобы создать сессию. Сохраните возвращённые sessionId и runId. Ответ приходит сразу со status: "running".
2

Дождитесь завершения хода

Передайте оба ID в wait-for-session. Если timedOut равно true, вызовите его снова с теми же ID. Тайм-аут не отменяет ход.
3

Прочитайте результат

Когда finished равно true, проверьте status. Изучите text, media и error (если есть) или откройте возвращённый url.
Для Python установите requests командой pip install requests. Для Node.js используйте Node.js 22+ и сохраните пример как example.mjs. Для примера с SDK нужно выполнить npm install @krea-ai/sdk; в нём для вызова HTTP-эндпоинтов используется requestRaw. Эти примеры отправляют одно сообщение и ждут до пяти минут. Они останавливаются при HTTP-ошибках, а также при неудачных или отменённых ходах. Отправка никогда не повторяется автоматически. Если запрос на отправку завершился по тайм-ауту, проверьте сессию в Krea, прежде чем отправлять снова: первый запрос мог уже запустить ход. Когда отведённое на ожидание время истекает, ход продолжается в фоновом режиме. Сохраните выведенные ID сессии и запуска, чтобы продолжить ожидание позже. timeoutSeconds — целое число от 1 до 300, по умолчанию 60. Тайм-аут вашего HTTP-клиента должен быть больше запрошенного времени ожидания. При ожидании после отправки всегда передавайте последний runId, чтобы финальный статус предыдущего хода не был принят за статус нового.

Чтение без ожидания

Используйте GET /agent/session/{sessionId}, чтобы получить снимок текущего состояния сессии:
cURL

Продолжение сессии

После завершения хода отправьте новое сообщение с его sessionId:
cURL
Сессия выполняет только один ход за раз. Отправка нового сообщения во время выполнения хода возвращает 409 с code: "conflict".

Входные данные и вложения

send-message принимает следующие поля. Полный enum моделей и схемы см. в справочнике. url вложения принимает доступный HTTP(S)-URL или авторизованный URI Krea Files, например file:550e8400-e29b-41d4-a716-446655440000. Необязательные name и contentType — непустые строки длиной до 255 символов, пробелы по краям обрезаются. Локальные пути на стороне вызывающего и ID OpenAI вида file_ не поддерживаются. Сначала передайте сам файл: ID в тексте промпта не передаёт его содержимое. Агент не наследует переписку и вложения вашего приложения. Прикрепляйте файлы-референсы, к которым у него нет доступа иным способом. Повторять в промпте пригодные URL, существующий контекст Krea или файлы из предыдущих ходов сессии не нужно.

Результаты сессии

send-message возвращает sessionId, threadId, runId, status (всегда "running") и url. GET /agent/session/{sessionId} и wait-for-session возвращают следующее представление сессии. Только wait-for-session добавляет обязательное поле timedOut. Каждый элемент media может представлять генерацию (jobId и необязательный mediaKind: image, video, audio или 3d), перезагруженный медиафайл (url, с необязательным mimeType) или файл Krea (uri, name, mimeType). Подробности генерации можно получить через GET /jobs/{jobId}. URI файла Krea можно повторно использовать как вложение или открыть url сессии, чтобы посмотреть её файлы. Медиафайлы могут появляться, пока ход ещё выполняется.

Ошибки

Ошибки эндпоинтов имеют формат { "error": "...", "code": "...", "allowedModels": ["..."] }. Обязательно только поле error. Ход, завершившийся неудачей после отправки, отображается как status: "failed" в успешном ответе с сессией.