ShvIA
TIMELINE
ACESSAR

Docs · Comece aqui

Início rápido

Esta página leva você de uma chave de API a uma resposta em stream. Reserve cerca de 5 minutos.

1. Obtenha uma chave de API#

Você precisa de uma conta no serviço e de uma chave de API dela. A chave tem o formato shvia_usr_<id>_<secret>, vale por 365 dias e aparece uma vez só, quando você a cria.

Crie no app: abra a sua conta, vá à seção de chave de API e escolha gerar uma chave. O app pede a sua senha. Autenticação explica as alternativas e o que fazer se a opção não aparecer: o acesso à API é habilitado por grupo de conta pelo operador, e uma conta nova pode ainda não tê-lo.

Mantenha a chave fora do controle de versão. Coloque-a no ambiente:

bash
export SHVIA_URL="https://ai.shvia.org"
export SHVIA_API_KEY="paste the key here"

2. Liste os modelos#

bash
curl -s "$SHVIA_URL/v1/models" \
  -H "Authorization: Bearer $SHVIA_API_KEY"
json
{
  "object": "list",
  "data": [
    { "id": "claude-sonnet-4-6@anthropic", "object": "model", "created": 1767225600, "owned_by": "shvia" },
    { "id": "gpt-4o@openai", "object": "model", "created": 1767225600, "owned_by": "shvia" }
  ]
}

O id de um modelo é <model>@<server>, onde o servidor é um provedor de nuvem ou um dos servidores do próprio operador. Use o id exatamente como listado e guarde-o numa variável:

bash
export SHVIA_MODEL="claude-sonnet-4-6@anthropic"

3. Envie uma mensagem#

bash
curl -s "$SHVIA_URL/v1/chat/completions" \
  -H "Authorization: Bearer $SHVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$SHVIA_MODEL"'",
    "messages": [{ "role": "user", "content": "Say hello in one short sentence." }]
  }'
json
{
  "id": "chatcmpl-0b0f3c0e-6c4e-4d6f-9a0e-2f3b1d7a9c11",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "claude-sonnet-4-6@anthropic",
  "choices": [
    { "index": 0, "message": { "role": "assistant", "content": "Hello! Nice to meet you." }, "finish_reason": "stop" }
  ],
  "usage": { "prompt_tokens": 14, "completion_tokens": 8, "total_tokens": 22 }
}

Defina sempre Content-Type: application/json. Sem ele o corpo não é lido como JSON e a requisição falha na validação.

4. Receba a resposta em stream#

Acrescente "stream": true e diga ao curl para não fazer buffer com -N:

bash
curl -sN "$SHVIA_URL/v1/chat/completions" \
  -H "Authorization: Bearer $SHVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$SHVIA_MODEL"'",
    "stream": true,
    "messages": [{ "role": "user", "content": "Count from 1 to 3." }]
  }'
sse
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1767225600,"model":"claude-sonnet-4-6@anthropic","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1767225600,"model":"claude-sonnet-4-6@anthropic","choices":[{"index":0,"delta":{"content":"1, 2, 3"},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1767225600,"model":"claude-sonnet-4-6@anthropic","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

5. Use um SDK#

Os SDKs oficiais da OpenAI funcionam apontando-os para o gateway. A URL base inclui /v1.

python
import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["SHVIA_URL"] + "/v1",
    api_key=os.environ["SHVIA_API_KEY"],
)

reply = client.chat.completions.create(
    model=os.environ["SHVIA_MODEL"],
    messages=[{"role": "user", "content": "Say hello in one short sentence."}],
)
print(reply.choices[0].message.content)
javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.SHVIA_URL + "/v1",
  apiKey: process.env.SHVIA_API_KEY,
});

const reply = await client.chat.completions.create({
  model: process.env.SHVIA_MODEL,
  messages: [{ role: "user", content: "Say hello in one short sentence." }],
});
console.log(reply.choices[0].message.content);

O que saber antes de construir#

  • Use ids completos e tenha a chave. Um nome sem @provider que o gateway não conhece não é recusado: é atendido por outro modelo, e o campo model da resposta mostra isso. Um modelo de nuvem para o qual você não tem chave pode ser trocado pelo seu modelo padrão sem nenhum sinal. Veja modelos.
  • Atenção ao limite de requisições. O padrão é 20 requisições por minuto por conta, um contador para todos os endpoints /v1 e alguns dos outros. Leia X-RateLimit-Remaining em cada resposta. Veja limites e cotas.
  • O content da mensagem é uma string. Arrays de partes de conteúdo, como os usados para imagens, são recusados com 422 no chat completions.
  • Os parâmetros de amostragem dependem do modelo. temperature e max_tokens valem para modelos cujo driver é ollama, e são ignorados nos outros, os modelos de nuvem incluídos. Veja chat completions.
  • Modelos de nuvem precisam da sua chave de provedor. Cadastre-a uma vez na sua conta. Veja provedores e suas chaves.

Próximos passos#