Referência Uncensored API: Campos Explicados

Convenções e transporte

A base URL é https://api.uncensoredapis.com/v1. Todos os corpos são JSON e UTF-8. Cada requisição carrega Authorization: Bearer <key>; uma chave ausente ou incorreta retorna 401. Existem apenas duas rotas, e qualquer outro caminho retorna 404.

Método	Caminho	Finalidade
POST	/v1/chat/completions	Gerar mensagem do assistente, opcionalmente em streaming
GET	/v1/models	Listar o id do modelo que você pode solicitar

A API é apenas texto. Não há rotas de embeddings, imagem, áudio ou vídeo nem fine-tuning, e existe exatamente um modelo, endereçado como uncensored. Como o formato de rede é compatível com a convenção de chat completions, os SDKs oficiais de Python e Node.js funcionam quando você substitui base_url. Os docs cobrem a configuração inicial; esta página é o complemento em nível de campo.

Campos do corpo da requisição

A tabela lista os campos que o endpoint entende. Campos de amostragem são passados para a geração sem alterações, então os valores que você escolhe se comportam como em qualquer API estilo chat-completions.

Campo	Tipo	Notas
model	string	Sempre "uncensored".
messages	array	Objetos ordenados com role (system, user, assistant, tool) e content.
max_tokens	integer	Limite de conclusão. Padrão 2048, máximo 32.000.
temperature	number	Aleatoriedade. Menor é mais determinístico.
top_p	number	Corte de amostragem de núcleo.
stop	string ou array	Sequências que encerram a geração.
stream	boolean	true altera a resposta para eventos enviados pelo servidor.
tools	array	Definições de funções no formato padrão JSON-schema.

Aqui está uma solicitação completa anotada. A mensagem do sistema define o comportamento, a mensagem do usuário carrega a tarefa e stop encerra a geração na primeira linha em branco.

Copycurl https://api.uncensoredapis.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "You are a terse release-notes writer."},
      {"role": "user", "content": "Summarize: fixed login bug, added dark mode."}
    ],
    "max_tokens": 120,
    "temperature": 0.4,
    "stop": ["\n\n"]
  }'

Duas regras de orçamento importam. Primeiro, o prompt mais a conclusão devem caber em 100.000 tokens, então uma requisição cujos tokens do prompt mais max_tokens excederem isso é rejeitada com 400. Segundo, o corpo serializado não pode exceder 8 MB. Se você enviar históricos longos, reduza as rodadas antigas do seu lado antes que se aproximem de qualquer limite.

O objeto de resposta

Uma chamada sem streaming retorna um objeto JSON. Leia-o de cima para baixo da seguinte forma.

Copy{
  "id": "chatcmpl-example123",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "uncensored",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "v1.4: Login bug fixed. Dark mode added."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 38,
    "completion_tokens": 14,
    "total_tokens": 52
  }
}

• id: um identificador único para a conclusão. Registre-o ao lado do seu próprio id de solicitação quando precisar correlacionar eventos.
• object: a constante chat.completion.
• created: timestamp Unix em segundos.
• model: ecoa uncensored.
• choices: um array. Você recebe uma entrada, então choices[0] é a resposta. index é sua posição.
• choices[].message: role é assistant; content contém o texto, ou é null quando o modelo retornou tool calls.
• choices[].finish_reason: por que a geração parou; veja a próxima seção.
• usage: contagem de tokens para faturamento, coberto abaixo.

Valores de finish_reason

Verifique finish_reason antes de confiar no conteúdo. Uma resposta truncada e uma resposta completa parecem idênticas até você verificar.

Valor	Significado	O que seu código deve fazer
stop	O modelo atingiu um fim natural ou atingiu uma de suas sequências stop.	Use o conteúdo como está.
length	O limite max_tokens (ou a janela de contexto) foi atingido no meio da resposta.	Aumente max_tokens, encurte o prompt ou peça ao modelo para continuar.
tool_calls	O modelo deseja que uma ou mais funções sejam executadas.	Execute-as e envie os resultados de volta como mensagens tool.

Quando o valor é tool_calls, a mensagem se parece com isto, com argumentos entregues como um JSON string que você deve analisar sozinho:

Copy{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc1",
        "type": "function",
        "function": {"name": "get_order", "arguments": "{\"order_id\": 8841}"}
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

Sempre envolva json.loads ou JSON.parse em arguments em tratamento de erros, porque o JSON gerado pode ocasionalmente estar malformado.

O bloco de uso e o que custa

usage relata prompt_tokens, completion_tokens e total_tokens. Estes são os números contra os quais seu saldo é cobrado: entrada a $0,25 por milhão de tokens e saída a $1,00 por milhão. O saldo pré-pago é deduzido por solicitação, sem assinatura.

Um exemplo prático sob as suposições declaradas: suponha que uma solicitação use 2.000 tokens de prompt e 500 tokens de conclusão. O custo de entrada é 2.000 / 1.000.000 x $0,25 = $0,0005. O custo de saída é 500 / 1.000.000 x $1,00 = $0,0005. A solicitação totaliza $0,0010. Essas contagens de tokens são suposições para aritmética, não uma medição de qualquer carga de trabalho real. A página de preços tem as tarifas em um só lugar.

Como os tokens de saída custam quatro vezes mais que os tokens de entrada, um max_tokens restrito é seu controle de custo mais direto.

Formato do chunk de streaming

Defina "stream": true e a resposta se torna text/event-stream. Cada evento é uma linha começando com data: seguida por JSON, separada por uma linha em branco. O tipo de objeto muda para chat.completion.chunk e message é substituído por delta.

Copydata: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"v1.4: "},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Login bug fixed."},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":38,"completion_tokens":14,"total_tokens":52}}

data: [DONE]

1. O primeiro chunk geralmente define delta.role para assistant com conteúdo vazio.
2. Os chunks de conteúdo carregam um fragmento em delta.content. Concatene-os na ordem de chegada.
3. O chunk de fechamento de conteúdo tem um delta vazio e um finish_reason não nulo.
4. Um chunk final com um array choices vazio carrega usage. Você não o solicita; ele é adicionado automaticamente.
5. O literal data: [DONE] termina o stream.

Proteja-se contra esse array choices vazio: indexar choices[0] no chunk de uso gera um erro em loops ingênuos. O exemplo do SDK abaixo lida com isso.

Copyimport os
from openai import OpenAI

client = OpenAI(base_url="https://api.uncensoredapis.com/v1", api_key=os.environ["API_KEY"])

reason, usage = None, None
for chunk in client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Name three uses of a rubber duck in debugging."}],
    stream=True,
):
    if chunk.choices:
        piece = chunk.choices[0].delta.content
        if piece:
            print(piece, end="", flush=True)
        if chunk.choices[0].finish_reason:
            reason = chunk.choices[0].finish_reason
    if getattr(chunk, "usage", None):
        usage = chunk.usage

print("\nfinish:", reason, "| tokens:", usage.total_tokens if usage else "n/a")

Para tool calls em streaming, delta.tool_calls chega em fragmentos; acumule a string arguments por índice de chamada e faça o parse uma vez quando finish_reason for tool_calls.

O endpoint de modelos

GET /v1/models precisa apenas do cabeçalho Bearer e retorna um objeto de lista. Como há um modelo, data contém uma entrada, uncensored. Clientes que preenchem um menu suspenso de modelos a partir desta rota mostrarão, portanto, uma única escolha.

Copycurl https://api.uncensoredapis.com/v1/models -H "Authorization: Bearer $API_KEY"

{
  "object": "list",
  "data": [
    {"id": "uncensored", "object": "model"}
  ]
}

Também é a maneira mais barata de verificar uma chave: 200 significa que a chave é válida, 401 significa que está errada ou foi regenerada. Chamar esta rota não gera tokens. Para tratamento de status e regras de retry, consulte o playbook de erros e rate limits.

Lista de verificação de referência para autores de clientes

Se você está escrevendo uma biblioteca de clientes ou envolvendo o endpoint em um gateway, verifique cada um desses comportamentos contra a especificação acima antes de enviar.

1. Higiene de cabeçalho. Envie a chave apenas no cabeçalho Authorization, nunca na string de consulta e nunca registre o valor do cabeçalho.
2. Analise defensivamente. Trate campos extras desconhecidos nas respostas como ignoráveis. Trave seu parser nos campos documentados aqui em vez de na ordem exata das chaves JSON.
3. Verifique finish_reason em cada resposta. Exiba um indicador visível quando for igual a length, caso contrário, os usuários leem texto cortado como a resposta completa.
4. Orçamento antes de enviar. Estime tokens de prompt, adicione seu max_tokens e compare a soma com 100.000. Rejeitar localmente é mais rápido do que esperar por um 400.
5. Lide com a cauda do stream. Espere um chunk com uma lista choices vazia e um objeto usage, então [DONE]. Feche a conexão após o sentinel.
6. Registre o uso. Armazene total_tokens por requisição para que você possa conciliar sua própria medição contra o saldo pré-pago mais tarde.
7. Respeite o limite. A conta permite 300 requisições por minuto por chave, então um gateway distribuindo muitos usuários precisa de sua própria fila.

Nenhum desses passos depende de um SDK de fornecedor. Um cliente HTTP simples que define o cabeçalho Bearer e decodifica JSON é suficiente, e os exemplos de SDK nesta página são conveniências, não requisitos. Combine esta lista de verificação com a tabela de erros no playbook e você cobre todo o ciclo de vida da requisição: construir, enviar, stream, analisar, contabilizar e recuperar.