Autenticação, acesso e cobrança
EnvieAuthorization: Bearer KREA_API_KEY em toda requisição para https://api.krea.ai. Chaves de API pessoais, de serviço e legadas usam a autenticação padrão da API pública.
Você só pode ler ou continuar sessões que pertencem ao chamador autenticado no workspace autenticado. Conhecer o ID de uma sessão não concede acesso. Arquivos anexados do Krea também precisam estar acessíveis a esse chamador nesse workspace.
Os turnos do Agent usam o saldo de unidades de computação do workspace. Eles não usam o saldo de API. Os direitos do plano do Agent e os limites de mensagens do plano Free continuam valendo. Veja Planos, acesso e créditos do Agent.
url onde você pode abrir a sessão no app do Krea com o acesso adequado à conta e ao workspace.
Inicie uma sessão e aguarde o resultado
Primeiro, definaKREA_API_KEY no seu ambiente. Escolha Bash com curl e jq, Python com requests ou Node.js com o fetch nativo ou o SDK do Krea.
1
Envie o primeiro turno
Omita
sessionId para criar uma sessão. Salve o sessionId e o runId retornados. A resposta volta imediatamente com status: "running".2
Aguarde este turno
Passe os dois IDs para
wait-for-session. Se timedOut for true, chame novamente com os mesmos IDs. Um tempo limite esgotado não cancela o turno.3
Leia o resultado
Verifique
status quando finished for true. Inspecione text, media e qualquer error, ou abra a url retornada.requests com pip install requests. Para Node.js, use Node.js 22+ e salve o exemplo como example.mjs. O exemplo com SDK requer npm install @krea-ai/sdk e usa requestRaw para chamar os endpoints HTTP.
Esses exemplos enviam uma mensagem e aguardam por até cinco minutos. Eles param em erros HTTP e em turnos que falharam ou foram cancelados. Eles nunca repetem um envio automaticamente. Se uma requisição de envio atingir o tempo limite, verifique a sessão no Krea antes de enviar novamente; a primeira requisição pode ter iniciado um turno.
Quando o tempo de espera se esgota, o turno continua em segundo plano. Salve os IDs de sessão e de execução exibidos para retomar a espera depois.
timeoutSeconds é um inteiro de 1 a 300 e o padrão é 60. Mantenha o tempo limite do seu cliente HTTP maior que a espera solicitada. Sempre passe o runId mais recente ao aguardar após um envio, para que o status final de um turno anterior não seja confundido com o do novo turno.
Ler sem esperar
UseGET /agent/session/{sessionId} para obter um snapshot da sessão atual:
cURL
Continuar a sessão
Depois que o turno terminar, envie outra mensagem com osessionId dele:
cURL
409 com code: "conflict".
Entradas e anexos
send-message aceita estes campos. Veja a referência para o enum completo de modelos e os schemas.
A
url do anexo aceita uma URL HTTP(S) acessível ou um URI autorizado do Krea Files, como file:550e8400-e29b-41d4-a716-446655440000. Os campos opcionais name e contentType são strings sem espaços nas extremidades, não vazias e com até 255 caracteres. Caminhos locais do chamador e IDs file_ da OpenAI não são suportados. Transfira o arquivo real primeiro; um ID no texto do prompt não transfere o conteúdo.
O Agent não herda a conversa nem os anexos da sua aplicação. Anexe arquivos de referência que não estejam acessíveis de outra forma. Você não precisa repetir URLs utilizáveis que já estejam no prompt, no contexto existente do Krea ou em arquivos de sessões anteriores.
Resultados da sessão
send-message retorna sessionId, threadId, runId, status (sempre "running") e url.
GET /agent/session/{sessionId} e wait-for-session retornam a seguinte visão da sessão. Somente wait-for-session adiciona o campo obrigatório timedOut.
Cada item de
media pode representar uma geração (jobId e mediaKind opcional: image, video, audio ou 3d), uma mídia rehospedada (url, com mimeType opcional) ou um arquivo do Krea (uri, name, mimeType). Obtenha os detalhes da geração por meio de GET /jobs/{jobId}. Você pode reutilizar o URI de um arquivo do Krea como anexo ou abrir a url da sessão para ver os arquivos. As mídias podem aparecer enquanto o turno ainda está em execução.
Erros
Os erros dos endpoints usam{ "error": "...", "code": "...", "allowedModels": ["..."] }. Apenas error é obrigatório. Um turno que falha após o envio aparece como status: "failed" em uma resposta de sessão bem-sucedida.