Autenticação, acesso e faturação
EnvieAuthorization: Bearer KREA_API_KEY em todos os pedidos para https://api.krea.ai. As chaves de API pessoais, de serviço e legadas utilizam a autenticação padrão da API pública.
Só pode ler ou continuar sessões que pertençam ao autor da chamada autenticado, na workspace autenticada. Conhecer o ID de uma sessão não concede acesso. Os anexos de ficheiros da Krea também têm de estar acessíveis a esse autor da chamada nessa workspace.
Os turnos do agente utilizam o saldo de unidades de computação da workspace. Não utilizam o saldo de API. Os direitos do plano do agente e os limites de mensagens do plano Free continuam a aplicar-se. Consulte Planos, acesso e créditos do agente.
url onde pode abrir a sessão na aplicação Krea com o acesso adequado à conta e à workspace.
Iniciar uma sessão e aguardar o resultado
Defina primeiroKREA_API_KEY no seu ambiente. Escolha Bash com curl e jq, Python com requests ou Node.js com o fetch integrado ou o SDK da Krea.
1
Submeter o primeiro turno
Omita
sessionId para criar uma sessão. Guarde o sessionId e o runId devolvidos. A resposta é devolvida de imediato com status: "running".2
Aguardar este turno
Passe ambos os IDs a
wait-for-session. Se timedOut for true, chame-o novamente com os mesmos IDs. Um tempo limite esgotado não cancela o turno.3
Ler o resultado
Verifique
status quando finished for true. Analise text, media e qualquer error, ou abra o url devolvido.requests com pip install requests. Para Node.js, utilize o Node.js 22+ e guarde o exemplo como example.mjs. O exemplo do SDK requer npm install @krea-ai/sdk e utiliza requestRaw para chamar os endpoints HTTP.
Estes exemplos submetem uma mensagem e aguardam até cinco minutos. Param perante erros HTTP e turnos falhados ou cancelados. Nunca repetem um envio automaticamente. Se um pedido de envio exceder o tempo limite, verifique a sessão na Krea antes de submeter novamente; o primeiro pedido pode ter iniciado um turno.
Quando o tempo de espera disponível se esgota, o turno continua em segundo plano. Guarde os IDs de sessão e de execução apresentados para retomar a espera mais tarde.
timeoutSeconds é um número inteiro de 1 a 300 e o valor predefinido é 60. Mantenha o tempo limite do seu cliente HTTP superior à espera pedida. Passe sempre o runId mais recente ao aguardar após um envio, para que o estado terminal de um turno anterior não seja confundido com o do novo turno.
Ler sem aguardar
UtilizeGET /agent/session/{sessionId} para obter um instantâneo da sessão atual:
cURL
Continuar a sessão
Depois de o turno terminar, envie outra mensagem com o respetivosessionId:
cURL
409 com code: "conflict".
Entradas e anexos
send-message aceita estes campos. Consulte a referência para o enum completo de modelos e os esquemas.
O
url do anexo aceita um 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. Os caminhos locais do autor da chamada e os IDs file_ da OpenAI não são suportados. Transfira primeiro o ficheiro real; um ID no texto do prompt não transfere o seu conteúdo.
O agente não herda a conversa nem os anexos da sua aplicação. Anexe os ficheiros de referência que não estejam acessíveis de outra forma. Não precisa de repetir URLs utilizáveis no prompt, contexto existente da Krea nem ficheiros de sessões anteriores.
Resultados da sessão
send-message devolve sessionId, threadId, runId, status (sempre "running") e url.
GET /agent/session/{sessionId} e wait-for-session devolvem a seguinte vista da sessão. Apenas wait-for-session acrescenta o campo obrigatório timedOut.
Cada item de
media pode representar uma geração (jobId e mediaKind opcional: image, video, audio ou 3d), media realojada (url, com mimeType opcional) ou um ficheiro da Krea (uri, name, mimeType). Obtenha os detalhes da geração através de GET /jobs/{jobId}. Pode reutilizar o URI de um ficheiro da Krea como anexo ou abrir o url da sessão para ver os respetivos ficheiros. A media pode aparecer enquanto o turno ainda está em execução.
Erros
Os erros dos endpoints utilizam{ "error": "...", "code": "...", "allowedModels": ["..."] }. Apenas error é obrigatório. Um turno que falhe após a submissão aparece, em vez disso, como status: "failed" numa resposta de sessão bem-sucedida.