Аутентификация, доступ и биллинг
Передавайте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.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" в успешном ответе с сессией.