API de IA Converya

Autenticação

Toda chamada leva a chave no cabeçalho Authorization: Bearer cvy_…. As chaves têm o formato cvy_ + 48 caracteres hexadecimais, validade de 30, 90 ou 365 dias e escopos. A chave aparece só uma vez, na criação: guardamos apenas uma impressão digital (SHA-256), então ninguém, nem a Converya, consegue ler a chave depois.

Nunca use a chave em código que roda no navegador ou no app do celular. Chame a API a partir do seu servidor, de uma função serverless ou de ferramentas como n8n. Se a chave vazar, revogue no painel: o efeito é imediato.

Idempotência

As criações (POST) exigem o cabeçalho Idempotency-Key com um valor único por pedido, por exemplo um UUID. Se a mesma chave chegar de novo (uma nova tentativa depois de uma queda de rede, por exemplo), a Converya não repete a chamada nem cobra de novo: responde 409 com o request_id do pedido original, que você consulta em /v1/usage.

HTTP/1.1 409 Conflict
{
  "error": { "message": "Esta Idempotency-Key já foi usada. …", "type": "idempotency_error", "param": "Idempotency-Key", "code": "idempotency_key_reused" },
  "request_id": "3f1c9a7e-0b2d-4e6f-8a1b-2c3d4e5f6a7b",
  "previous_status": "ok",
  "previous_created_at": "2026-10-28T13:05:11.204Z"
}

Depois de um erro, tente de novo com uma chave nova. Sem o cabeçalho, a resposta é 400 idempotency_key_required.

Modelos

Qualquer outro nome de modelo enviado no chat é tratado como converya-auto. As respostas sempre devolvem o nome converya-*. Esta rota aceita chamadas do navegador (CORS liberado só para ela).

Chat

curl https://www.converya.com/api/v1/chat/completions \
  -H "Authorization: Bearer $CONVERYA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c0e2f1a-4b9d-4c3e-9a51-2f6d8b1e0c11" \
  -d '{
    "model": "converya-auto",
    "messages": [
      {"role": "system", "content": "Você é um atendente de loja, educado e objetivo."},
      {"role": "user", "content": "Tem frete grátis para São Paulo?"}
    ],
    "max_tokens": 300
  }'

Resposta no formato OpenAI, com o campo extra converya: charged_brl é o valor exato debitado da carteira e request_id identifica o pedido no extrato de uso.

{
  "id": "chatcmpl-3f1c9a7e0b2d4e6f8a1b2c3d4e5f6a7b",
  "object": "chat.completion",
  "created": 1793000000,
  "model": "converya-auto",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Temos sim! Para a capital paulista o frete é grátis acima de R$ 99." },
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": { "prompt_tokens": 41, "completion_tokens": 22, "total_tokens": 63 },
  "converya": { "charged_brl": 0.000312, "request_id": "3f1c9a7e-0b2d-4e6f-8a1b-2c3d4e5f6a7b" }
}

Para ler uma imagem, mande partes no content:

{
  "model": "converya-auto",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "Descreva este produto para um anúncio." },
      { "type": "image_url", "image_url": { "url": "https://exemplo.com/produto.jpg" } }
    ]
  }]
}

Streaming

Com stream: true a resposta chega em text/event-stream, em pedaços chat.completion.chunk, terminando em data: [DONE]. O último pedaço com finish_reason traz o recibo converya. Comstream_options.include_usage, um pedaço final traz usage. Se faltar saldo, a resposta é 402 antes de abrir o stream; se o fornecedor falhar no meio, chega um evento com error antes do [DONE].

curl -N https://www.converya.com/api/v1/chat/completions \
  -H "Authorization: Bearer $CONVERYA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model":"converya-auto","stream":true,"stream_options":{"include_usage":true},
       "messages":[{"role":"user","content":"Escreva 3 títulos para um anúncio de açaí"}]}'

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"converya-auto","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"converya-auto","choices":[{"index":0,"delta":{"content":"1. Açaí"},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"converya-auto","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"converya":{"charged_brl":0.00041,"request_id":"…"}}

data: [DONE]

Imagens

curl https://www.converya.com/api/v1/images/generations \
  -H "Authorization: Bearer $CONVERYA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "converya-image",
    "prompt": "Foto de produto: pote de açaí com morangos, fundo roxo, luz de estúdio",
    "size": "1024x1024",
    "n": 1,
    "response_format": "url"
  }'

Edição com referência (produto num cenário novo):

{
  "model": "converya-image-edit",
  "prompt": "Coloque este produto numa bancada de mármore com luz da manhã",
  "images": ["https://exemplo.com/meu-produto.jpg"],
  "size": "1024x1024"
}

Uma imagem leva de 10 a 40 segundos. Ajuste o tempo limite do seu cliente HTTP para pelo menos 120 s.

Uso e saldo

curl "https://www.converya.com/api/v1/usage?limit=20&since=2026-10-01" \
  -H "Authorization: Bearer $CONVERYA_API_KEY"

curl https://www.converya.com/api/v1/balance -H "Authorization: Bearer $CONVERYA_API_KEY"

{
  "object": "list",
  "since": "2026-10-01T00:00:00.000Z",
  "total_requests": 128,
  "total_charged_brl": 1.284,
  "data": [
    { "id": "…", "object": "usage.record", "created": 1793000000, "model": "converya-auto",
      "status": "ok", "input_tokens": 41, "output_tokens": 22, "units": 0, "charged_brl": 0.000312,
      "latency_ms": 1180, "idempotency_key": "7c0e2f1a-…", "api_key_id": "…" }
  ]
}

{ "object": "balance", "currency": "BRL", "balance_brl": 48.715688, "balance_micro": 48715688, "topup_url": "https://www.converya.com/app/api/carteira" }

Erros

Os erros seguem o formato da OpenAI, então os SDKs tratam do jeito de sempre.

{
  "error": {
    "message": "Saldo insuficiente na carteira. Recarregue em Converya → API e carteira.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_balance"
  }
}

Preços e cobrança

O valor de cada chamada é o custo do modelo usado × o multiplicador da sua conta, convertido para reais pelo câmbio do dia configurado na plataforma. No texto, o custo vem dos tokens de entrada e de saída; nas imagens, de cada imagem gerada. O valor exato de cada chamada vem no recibo converya.charged_brl e no extrato de /v1/usage. No painel, a aba Chaves e guia mostra a estimativa por modelo para a sua conta.

• Carteira pré-paga em reais, recarregada por cartão. O saldo não expira.
• Chamadas com erro do fornecedor não são cobradas.
• Sem mensalidade para usar a API: você paga o que consumir.

SDKs e ferramentas

Funciona com os SDKs oficiais da OpenAI (JavaScript, Python e outros), LangChain, Vercel AI SDK, n8n (credencial OpenAI com URL base personalizada) e qualquer ferramenta que aceite um endpoint compatível com OpenAI. Basta apontar o endereço base para https://www.converya.com/api/v1 e enviar o Idempotency-Key nas criações.