Skip to main content
Usa la Agent API para encargarle una tarea a Krea Agent desde tu propia aplicación. Las solicitudes y respuestas usan campos JSON en camelCase. El agente trabaja en segundo plano mientras tu aplicación lee su progreso y sus resultados.
El agente trabaja en segundo plano. No hace preguntas, y las solicitudes de confirmación de costos y permisos se aprueban automáticamente. Incluye todos los requisitos y restricciones en tu prompt. Revisa la tarea antes de enviarla.

Autenticación, acceso y facturación

Envía Authorization: Bearer KREA_API_KEY con cada solicitud a https://api.krea.ai. Las claves de API personales, de servicio y heredadas usan la autenticación estándar de la API pública. Solo puedes leer o continuar sesiones que pertenezcan al usuario autenticado en el workspace autenticado. Conocer el ID de una sesión no otorga acceso. Los archivos de Krea adjuntos también deben ser accesibles para ese usuario en ese workspace.
Los turnos del agente usan el saldo de unidades de cómputo del workspace. No usan el saldo de API. Los derechos del plan de Agent y los límites de mensajes del plan Free siguen aplicándose. Consulta Planes, acceso y créditos de Agent.
Cada respuesta incluye una url con la que puedes abrir la sesión en la app de Krea si tienes el acceso adecuado a la cuenta y al workspace.

Iniciar una sesión y esperar su resultado

Primero, define KREA_API_KEY en tu entorno. Elige Bash con curl y jq, Python con requests o Node.js con fetch integrado o el SDK de Krea.
1

Envía el primer turno

Omite sessionId para crear una sesión. Guarda el sessionId y el runId devueltos. La respuesta llega de inmediato con status: "running".
2

Espera a que termine este turno

Pasa ambos IDs a wait-for-session. Si timedOut es true, vuelve a llamarlo con los mismos IDs. Agotar el tiempo de espera no cancela el turno.
3

Lee el resultado

Comprueba status cuando finished sea true. Revisa text, media y cualquier error, o abre la url devuelta.
Para Python, instala requests con pip install requests. Para Node.js, usa Node.js 22+ y guarda el ejemplo como example.mjs. El ejemplo del SDK requiere npm install @krea-ai/sdk y usa requestRaw para llamar a los endpoints HTTP. Estos ejemplos envían un mensaje y esperan hasta cinco minutos. Se detienen ante errores HTTP y turnos fallidos o cancelados. Nunca reintentan un envío automáticamente. Si una solicitud de envío agota su tiempo de espera, revisa la sesión en Krea antes de volver a enviarla; es posible que la primera solicitud ya haya iniciado un turno. Cuando se agota el tiempo de espera, el turno continúa en segundo plano. Guarda los IDs de sesión y de ejecución que se imprimen para reanudar la espera más tarde. timeoutSeconds es un entero de 1 a 300 y su valor predeterminado es 60. Mantén el tiempo de espera de tu cliente HTTP por encima de la espera solicitada. Pasa siempre el runId más reciente al esperar después de un envío, para que el estado terminal de un turno anterior no se confunda con el del nuevo turno.

Leer sin esperar

Usa GET /agent/session/{sessionId} para obtener una instantánea de la sesión actual:
cURL

Continuar la sesión

Cuando termine el turno, envía otro mensaje con su sessionId:
cURL
Una sesión ejecuta un turno a la vez. Enviar otro mensaje mientras hay un turno en curso devuelve 409 con code: "conflict".

Entradas y archivos adjuntos

send-message acepta estos campos. Consulta la referencia para ver el enum completo de modelos y los esquemas. La url de un archivo adjunto acepta una URL HTTP(S) accesible o un URI autorizado de Krea Files, como file:550e8400-e29b-41d4-a716-446655440000. Los campos opcionales name y contentType son cadenas no vacías, con los espacios recortados, de hasta 255 caracteres. No se admiten rutas locales del usuario ni IDs file_ de OpenAI. Transfiere primero el archivo real; un ID en el texto del prompt no transfiere su contenido. El agente no hereda la conversación ni los archivos adjuntos de tu aplicación. Adjunta los archivos de referencia que no sean accesibles de otra forma. No necesitas repetir las URLs utilizables que ya estén en el prompt, en el contexto existente de Krea o en archivos anteriores de la sesión.

Resultados de la sesión

send-message devuelve sessionId, threadId, runId, status (siempre "running") y url. GET /agent/session/{sessionId} y wait-for-session devuelven la siguiente vista de la sesión. Solo wait-for-session añade el campo obligatorio timedOut. Cada elemento de media puede representar una generación (jobId y mediaKind opcional: image, video, audio o 3d), contenido multimedia realojado (url, con mimeType opcional) o un archivo de Krea (uri, name, mimeType). Obtén los detalles de la generación mediante GET /jobs/{jobId}. Puedes reutilizar el URI de un archivo de Krea como archivo adjunto o abrir la url de la sesión para ver sus archivos. El contenido multimedia puede aparecer mientras el turno sigue en curso.

Errores

Los errores de los endpoints usan { "error": "...", "code": "...", "allowedModels": ["..."] }. Solo error es obligatorio. Un turno que falla después de enviarse aparece, en cambio, como status: "failed" en una respuesta de sesión exitosa.