DOCUMENTAÇÃO

Introdução

Integre respostas de texto no seu produto usando uma API B2B simples, com crédito pré-pago e repetição segura.

Estado atual: API em piloto fechado. A capacidade disponível é texto síncrono; não há streaming, voz ou imagens.

Início rápido

Receba uma chave de projeto tc_live_… ou tc_test_… por canal seguro.
No servidor, gere um UUID novo para Idempotency-Key.
Faça POST /v1/responses.
Em falha de rede, repita o mesmo pedido com a mesma chave.

Chaves e segurança

Uma chave nunca pode entrar no browser, app móvel distribuído, repositório ou variável PUBLIC_. Guarde-a apenas no servidor da integração. Não há acesso comercial aberto, recarga pública, voz, imagens ou SSE nesta versão.

Referência: criar uma resposta

POST https://api.tipochat.co.mz/v1/responses

Campo	Obrigatório	Regra
`Authorization`	sim	`Bearer tc_live_…`; use somente no servidor.
`Idempotency-Key`	sim	8–255 caracteres; reutilize apenas para a mesma operação.
`input`	sim	Texto não vazio, até 8.000 caracteres.
`instructions`	não	Texto até 2.000 caracteres.
`model`	não	Se enviado, deve ser `tipo-text`.
`max_output_tokens`	não	Inteiro entre 1 e 2.048; padrão 512.
`stream`	não	Não use `true`; streaming ainda não existe.

Resposta de sucesso

{
  "id": "resp_…", "object": "response", "model": "tipo-text",
  "output_text": "Olá! Como posso ajudar?",
  "usage": { "input_tokens": 12, "output_tokens": 8, "total_tokens": 20 },
  "billing": { "mode": "live", "currency": "MZN", "charged_micro_mzn": 9400 }
}

JavaScript (Node.js)

const response = await fetch("https://api.tipochat.co.mz/v1/responses", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.TIPOCHAT_API_KEY}`,
    "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ model: "tipo-text", input: "Resume este texto: …", max_output_tokens: 180 }),
});
const body = await response.json();
if (!response.ok) throw new Error(body.error?.code || "tipochat_error");
console.log(body.output_text);

PHP (cURL)

<?php
$curl = curl_init("https://api.tipochat.co.mz/v1/responses");
curl_setopt_array($curl, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POSTFIELDS => json_encode(["model" => "tipo-text", "input" => "Escreve uma saudação curta."]),
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("TIPOCHAT_API_KEY"),
    "Content-Type: application/json", "Idempotency-Key: " . bin2hex(random_bytes(16))]]);
$body = curl_exec($curl); $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE); curl_close($curl);
if ($status < 200 || $status >= 300) throw new RuntimeException($body ?: "TipoChat request failed");
echo json_decode($body, true)["output_text"];

Erros e repetição segura

HTTP / código	Causa provável	Ação
`400 invalid_request`	Corpo, limite ou modelo inválido.	Corrija o pedido e use outra chave.
`401 invalid_api_key`	Chave ausente, expirada, revogada ou sem escopo.	Verifique-a no servidor.
`402 insufficient_balance`	Saldo insuficiente.	Aguarde uma recarga validada.
`409 idempotency_key_reused`	Chave repetida com outro corpo.	Use chave nova.
`409 request_in_progress`	Operação original em curso.	Aguarde e repita a mesma chave.
`502 provider_error`	Fornecedor indisponível.	Retry exponencial após erro final.
`503 service_unavailable`	Manutenção ou segurança.	Consulte o estado.

A mesma chave com o mesmo corpo devolve a resposta guardada; com corpo diferente devolve 409. Use x-request-id para diagnóstico.

Preços e pagamentos

Produto	Unidade	Preço público	Estado
`tipo-text`	Tokens de entrada e saída	Definido no contrato/piloto e no `price_book` ativo	Piloto fechado

A cobrança reserva saldo antes da chamada e liquida apenas o uso devolvido. Recargas M-Pesa, e-Mola e mKesh serão publicadas somente depois de uma transação real reconciliada.

Sandbox

Após a publicação técnica, uma chave de projeto test devolve resposta simulada pela mesma rota, com billing.mode = "sandbox" e charged_micro_mzn = 0. O sandbox não chama a OpenAI, não reserva saldo e mantém a idempotência por 24 horas.

Alterações

4 de agosto de 2026: primeira versão pública da documentação; texto síncrono em piloto fechado.