Chat stream

Os endpoints de chat nativos são os que os apps do ShvIA usam. Em comparação com os endpoints /v1, eles guardam as suas conversas no servidor e aceitam um esforço de raciocínio. POST /api/v1/chat também aceita anexos de arquivo e pode usar os seus combos. Eles têm ainda convenções próprias, descritas aqui.

POST/api/v1/chat#

Devolve a resposta em streaming, como server-sent events.

• Auth: a sua chave de API.
• Limite: 60 requisições por minuto por conta por padrão. Veja limites e cotas.
• Corpo: JSON, ou multipart/form-data quando você envia arquivos.

curl -sN "$SHVIA_URL/api/v1/chat" \
  -H "Authorization: Bearer $SHVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Say hello in one short sentence.",
    "profile_name": "'"$SHVIA_MODEL"'",
    "session_id": "support-ticket-1042"
  }'

Requisição#

Quando nenhum modelo é informado, o gateway usa o seu padrão salvo e, depois, o padrão da instalação. Não existe temperature, nem max_tokens, nem o campo system, nem como enviar uma lista de mensagens: a conversa é a que está guardada no servidor, e o servidor acrescenta as próprias instruções a ela.

Com um único modelo, este endpoint não recorre ao seu modelo padrão como /v1 e agent/chat fazem: um modelo sem chave por trás, ou que falha, termina num evento error. Dê a ele outros modelos para tentar com um combo.

Anexos#

• Arquivos de texto e de código: até 10 por mensagem, 262144 bytes cada e 1048576 bytes no total.
• Imagens: PNG, JPEG, WebP ou GIF, até 8 por mensagem e 20 MiB cada. Envie só para um modelo que enxerga imagens, ou a requisição é recusada.
• Pacotes (zip, tar, tgz) são abertos e os arquivos de texto dentro deles são usados.
• O grupo da sua conta define mais um limite para o número de anexos por mensagem.

Conversas e session_id#

Com uma chave de API, toda chamada a este endpoint pertence a uma conversa num projeto chamado API. Se a chamada continua uma conversa anterior ou não, isso depende de session_id:

• Com session_id: a conversa mais recente sua com esse mesmo valor continua, e os turnos anteriores são enviados ao modelo, quantos couberem na janela de contexto dele: os mais antigos podem ser resumidos ou deixados de fora. Um valor novo começa uma conversa nova.
• Sem ele: toda chamada é uma conversa nova com um turno.

O stream nunca diz o id da conversa. Para lê-lo depois, liste as suas conversas e compare o campo session_id. Veja conversas. Você não pode enviar um conversation_id a este endpoint; para continuar uma conversa pelo id, use POST /api/v1/agent/chat.

O stream#

A resposta é text/event-stream. Cada evento é uma linha, data: {"kind": "…", "data": {…}}, seguida de uma linha em branco. Não há linhas event: nem id:, e nenhum comentário de keep-alive. Como a requisição é um POST com headers, o EventSource de um navegador não pode ser usado: leia o stream do corpo. Ignore qualquer kind que você não conheça, já que novos são acrescentados com o tempo. Tire a resposta final de done. Se a instalação deixa o chat usar ferramentas, o stream também pode trazer tool_call, tool_result e eventos parecidos, e um evento text_clear, que quer dizer que o texto mostrado até agora deve ser descartado.

data: {"kind":"user_message","data":{"id":5121}}

data: {"kind":"model","data":{"name":"claude-sonnet-4-6@anthropic","model":"claude-sonnet-4-6","profile":"claude-sonnet-4-6@anthropic","server":"anthropic","server_label":"…","target_source":"request","request_id":"3b1a8f7e-…"}}

data: {"kind":"text_delta","data":{"delta":"Hello"}}

data: {"kind":"text_delta","data":{"delta":"! Nice to meet you."}}

data: {"kind":"usage","data":{"model":"claude-sonnet-4-6","profile":"claude-sonnet-4-6@anthropic","server":"anthropic","server_label":"…","prompt_tokens":42,"completion_tokens":8,"total_tokens":50,"thinking_time_ms":null,"response_time_ms":890.4,"reasoning_tokens":null,"effort":"medium","cost":null,"cost_estimated":0.000246}}

data: {"kind":"done","data":{"text":"Hello! Nice to meet you."}}

cost é o custo que o provedor informou, em USD, ou null. cost_estimated é o número de tokens vezes a tabela de preços, ou null. usage.effort é o nível de esforço que o modelo realmente aplicou, ou null. Os tempos são números que podem ter casas decimais, então leia-os como float. Atenção: um data vazio é escrito como [], não como {}.

Códigos de erro#

Quando um evento error tem codigo, decida por ele. message é para pessoas e pode estar em outro idioma.

Um stream cortado por timeout envia um error sem codigo, depois usage, depois done com o texto parcial, que é salvo. Uma resposta com um laço repetitivo é entregue e salva com um evento warn a mais.

Mais uma coisa a saber: se a conta tem aberta no app web uma conversa com um bot, o modelo ao qual o bot está fixado vale mais que o que você pediu. Leia o evento model para ver o que rodou.

POST/api/v1/agent/chat#

Uma chamada que bloqueia, uma resposta JSON.

• Auth: a sua chave de API. Uma chave cujo grupo de conta não tem acesso à API é recusada com 401.
• Limite: 20 requisições por minuto por conta por padrão, no contador que os outros endpoints limitados dividem. Veja limites e cotas.

curl -s "$SHVIA_URL/api/v1/agent/chat" \
  -H "Authorization: Bearer $SHVIA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "message": "Say hello in one short sentence.", "profile_name": "'"$SHVIA_MODEL"'" }'

{
  "request_id": "9eaa5ed8-e7fa-423b-9a93-d9ff3d4c8a03",
  "response": "Hello! Nice to meet you.",
  "model": "claude-sonnet-4-6",
  "server": "anthropic",
  "server_label": "…",
  "profile_name": "claude-sonnet-4-6@anthropic",
  "target_source": "request",
  "effort": null,
  "tokens": { "prompt": 42, "completion": 8, "total": 50 },
  "timing": { "queue_wait_ms": 0, "response_time_ms": 890 },
  "conversation_id": 5
}

Requisição#

Como os endpoints /v1, este monta uma cadeia curta: o modelo que você pediu e depois o modelo padrão da sua conta. Um modelo de nuvem sem chave por trás, ou que falha com algo que outro modelo pode resolver antes de enviar qualquer texto, é substituído pelo modelo padrão, e a resposta nomeia o modelo que respondeu: leia model, server e profile_name. Veja modelos.

Para manter uma conversa de vários turnos, devolva o conversation_id da resposta anterior. Aqui não há session_id, nem anexos, nem streaming. timing.queue_wait_ms é sempre 0.

Erros#

Este endpoint responde com status HTTP e um texto detail, e sem codigo:

Um 403 aqui não é limite de requisições: não tente de novo sem mudar alguma coisa.