PT ▾
Obter chave de API
API sem censura compatível com OpenAI para desenvolvedores.Atualizado

Modo JSON e chamada de funções no Uncensored LLM API

O interruptor do modo JSON da API LLM sem censura é o mesmo que você já conhece dos clientes OpenAI: envie response_format com type json_object e a resposta volta como um objeto JSON. Esta página cobre isso, além da chamada de ferramentas, com código que você pode executar no endpoint ao vivo.

Colchetes brilhantes montados a partir de cubos com um braço mecânico, ilustrando saída JSON estruturada e chamadas de ferramentas

Início rápido com curl

A menor solicitação de modo JSON que funciona é assim. Ela usa a URL base https://api.uncensoredllmapi.com/v1, o modelo uncensored e sua chave como token Bearer:

curl https://api.uncensoredllmapi.com/v1/chat/completions   -H "Authorization: Bearer $UNCENSORED_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "uncensored",
    "response_format": {"type": "json_object"},
    "messages": [
      {"role": "system", "content": "Reply only with a JSON object."},
      {"role": "user", "content": "Create a tavern NPC with keys name, trade and rumour."}
    ]
  }'

A mensagem do assistente em choices[0].message.content é uma string contendo um objeto JSON. Você ainda precisa fazer o parse manualmente. Não pule a instrução no prompt: o modo JSON restringe a saída para ser um objeto, mas não consegue adivinhar quais chaves você quer. Nomear as chaves e, idealmente, mostrar um exemplo de uma linha é o que garante uma estrutura estável.

Se você ainda não tem uma chave, a página da chave de API concede $0,50 de crédito de teste com um clique após o cadastro. Esse crédito não precisa de pagamento, dura 7 dias e é limitado a um por pessoa.

Modo JSON em Python com validação

Trate a saída do modelo como qualquer outra entrada externa. Faça o parse, verifique contra um esquema e tente novamente um número limitado de vezes se falhar. O Pydantic torna isso curto:

import json, os
from openai import OpenAI
from pydantic import BaseModel, ValidationError

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

class Npc(BaseModel):
    name: str
    trade: str
    rumour: str

SYSTEM = (
    "Reply only with a JSON object with exactly these keys: "
    "name, trade, rumour. Each value is a string."
)

def make_npc(setting, tries=3):
    for _ in range(tries):
        r = client.chat.completions.create(
            model="uncensored",
            response_format={"type": "json_object"},
            messages=[
                {"role": "system", "content": SYSTEM},
                {"role": "user", "content": f"Setting: {setting}"},
            ],
            temperature=0.7,
            max_tokens=300,
        )
        choice = r.choices[0]
        if choice.finish_reason == "length":
            continue           # cut off, so the JSON is incomplete
        try:
            return Npc(**json.loads(choice.message.content))
        except (json.JSONDecodeError, ValidationError, TypeError):
            continue
    raise RuntimeError("no valid JSON after retries")

print(make_npc("a river port in a plague year"))

Três hábitos nesse snippet valem a pena copiar. O código verifica finish_reason antes de fazer o parse, porque uma resposta que para em max_tokens termina no meio do objeto. Ele usa uma temperatura moderada, já que temperaturas altas tornam a saída malformada mais provável. E ele limita as tentativas, para que um prompt ruim não gire para sempre. Como requisições falhas ou recusadas não são cobradas, o orçamento de retry é uma questão de latência, não de custo.

Erros comuns no modo JSON

  • Pedir JSON no prompt, mas não em response_format. O modelo geralmente cumpre, mas pode envolver o objeto em texto corrido ou em um bloco de código. Defina ambos.
  • Definir max_tokens muito baixo. Estime a resposta válida mais longa e adicione margem. Uma longa lista de itens pode facilmente exceder 300 tokens.
  • Esperando uma matriz de nível superior. O modo JSON pede um objeto. Se você precisar de uma lista, peça {"items": [...]}.
  • Empilhar uma sequência de parada que aparece no JSON. O parâmetro stop é repassado, e uma string de parada que aparece dentro de um valor corta a resposta prematuramente.
  • Usar o modo JSON com streaming e fazer o parse de cada chunk. Colete o texto inteiro primeiro, depois faça o parse uma vez no final.

Configurações de amostragem como temperatura, top_p, seed e as penalidades são repassadas. Para tarefas de extração, uma temperatura baixa em torno de 0.2 e uma seed fixa fornecem a saída mais repetível. Para geração criativa como o NPC acima, um valor mais alto é aceitável desde que você valide.

Chamada de funções: o ciclo completo

A chamada de funções permite que o modelo peça ao seu código para fazer algo e depois continue com o resultado. O fluxo tem quatro etapas: você declara as ferramentas, o modelo responde com tool_calls, você as executa e envia os resultados de volta como mensagens com role: "tool".

import json, os
from openai import OpenAI

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

tools = [{
    "type": "function",
    "function": {
        "name": "lookup_inventory",
        "description": "Return the stock count for an item in the shop.",
        "parameters": {
            "type": "object",
            "properties": {"item": {"type": "string"}},
            "required": ["item"],
        },
    },
}]

def lookup_inventory(item):
    stock = {"healing potion": 4, "rope": 12}
    return {"item": item, "count": stock.get(item.lower(), 0)}

messages = [{"role": "user", "content": "Do you still have healing potions?"}]

for _ in range(4):                      # hard cap on tool rounds
    r = client.chat.completions.create(
        model="uncensored", messages=messages, tools=tools, tool_choice="auto"
    )
    msg = r.choices[0].message
    if not msg.tool_calls:
        print(msg.content)
        break
    messages.append(msg)
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        result = lookup_inventory(**args)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result),
        })

Os argumentos chegam como uma string JSON, que você deve fazer o parse, e o modelo ocasionalmente pode produzir argumentos que não correspondem ao seu esquema. Valide-os antes de executar qualquer coisa com efeitos colaterais. Nunca os passe para um shell, uma string SQL ou um caminho de arquivo sem verificações.

O campo tool_choice permite direcionar o comportamento. Deixe em "auto" e o modelo decide. Nomeie uma função específica para forçar uma chamada, o que é útil quando você quer extração estruturada através de um schema de ferramenta em vez do modo JSON.

Streaming de chamadas de funções em Node

Com stream: true, as chamadas de funções chegam em pedaços. Cada chunk carrega um fragmento do nome da função ou da string de argumentos, indexado por posição. Você precisa concatenar os fragmentos por índice e fazer o parse apenas quando o stream termina.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.uncensoredllmapi.com/v1",
  apiKey: process.env.UNCENSORED_API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "Check stock for rope." }],
  tools: [{
    type: "function",
    function: {
      name: "lookup_inventory",
      description: "Return the stock count for an item.",
      parameters: {
        type: "object",
        properties: { item: { type: "string" } },
        required: ["item"],
      },
    },
  }],
});

const calls = [];
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta;
  for (const tc of delta?.tool_calls ?? []) {
    const slot = (calls[tc.index] ??= { id: "", name: "", args: "" });
    if (tc.id) slot.id = tc.id;
    if (tc.function?.name) slot.name += tc.function.name;
    if (tc.function?.arguments) slot.args += tc.function.arguments;
  }
}

for (const c of calls) {
  console.log(c.name, JSON.parse(c.args));
}

Lembre-se de que uma solicitação em streaming ocupa um dos seus slots de concorrência até o stream terminar. Uma chave completa permite 8 solicitações simultâneas e 300 por minuto; uma chave de teste, 2 e 60. Ultrapassar qualquer limite gera HTTP 429 com o código concurrency ou rate_limited. O total de uso é reportado no final do stream, o que é útil para registrar custos.

Modo JSON ou um esquema de ferramenta

Ambos fornecem dados estruturados, então qual você deve usar? A pergunta decisiva é se o modelo está produzindo dados ou escolhendo uma ação.

Use o modo JSON quando a própria saída for o produto: uma ficha de NPC, uma lista de tags, uma classificação com um campo de confiança. Você controla todo o prompt, recebe um objeto de volta e há apenas uma solicitação para pagar.

Use ferramentas quando o modelo precisa decidir se deve agir, ou quando várias ações diferentes são possíveis. Um schema por função documenta o contrato, tool_choice permite forçar ou permitir uma chamada, e o loop na seção anterior lida com trabalho multi-etapa. O custo é uma requisição extra por rodada, além das definições de ferramentas contadas como input toda vez.

Um caminho intermediário prático para extração: declare uma ferramenta cujos parâmetros são os campos que você quer, e defina tool_choice para essa função. Você obtém um JSON de argumentos que segue a forma do schema sem escrever a lista de chaves no prompt. De qualquer forma, valide o resultado antes de confiar nele e registre o valor X-Request-Id de qualquer requisição que produziu algo inesperado.

Quanto custa

JSON e chamadas de ferramentas são cobrados como qualquer outro token: $0,15 por 1M de input e $0,50 por 1M de output. As definições de ferramentas contam como input em cada solicitação, e cada resultado de ferramenta que você envia de volta adiciona ao input da próxima solicitação.

Exemplo: uma rodada de assistente usando ferramentas com um schema de ferramenta e prompt de 600 tokens, uma chamada de modelo de 150 tokens, depois uma segunda solicitação contendo 900 tokens de input (as mensagens anteriores mais um resultado de ferramenta) e uma resposta de 200 tokens.

  • Solicitação um: 600 input e 150 output. Input 600 x $0,15 / 1M = $0,00009. Output 150 x $0,50 / 1M = $0,000075. Subtotal $0,000165.
  • Solicitação dois: 900 input e 200 output. Input 900 x $0,15 / 1M = $0,000135. Output 200 x $0,50 / 1M = $0,0001. Subtotal $0,000235.
  • Total para a rodada: $0,0004.

A essa taxa, 1.000 rodadas custam $0,40. O crédito é pré-pago em valores inteiros de $20 a $500 (bônus: +5% a partir de $50, +10% a partir de $100, +15% a partir de $200), pago em cripto com USDT na TRC20 ou USDC na Base. Veja a página de preços para os valores atuais.

Para onde ir a seguir

A referência para cada campo da solicitação está na documentação da API. Se você está preparando um aplicativo para tráfego real, a lista de verificação de produção é a próxima página para ler, e o suporte pode ajudar se uma solicitação se comportar de forma inesperada. Mantenha o ID da sua solicitação, que é retornado no cabeçalho X-Request-Id, à mão.

O serviço é apenas de texto e a janela de contexto é de 100.000 tokens, incluindo suas definições de ferramentas e resultados. Conteúdo sexual envolvendo menores de idade não é permitido, e isso se aplica à saída estruturada e orientada por ferramentas exatamente como se aplica ao chat simples.

Perguntas e respostas

O modo JSON garante meu esquema exato?

Não. Isso faz com que a resposta seja um objeto JSON, mas as chaves vêm do seu prompt. Valide o resultado com uma biblioteca de esquemas e tente novamente se falhar.

Como envio os resultados das ferramentas de volta?

Anexe a mensagem do assistente que continha tool_calls, depois adicione uma mensagem por chamada com role tool, o tool_call_id correspondente e o resultado como string.

Posso fazer streaming das chamadas de ferramentas?

Sim. Com stream definido como true, os tool_calls chegam em fragmentos. Concatene as strings de nome e argumentos por índice e processe uma única vez quando o stream terminar.

Respostas JSON inválidas são cobradas?

Uma resposta que é concluída é cobrada, mesmo que seu parser a rejeite. Requisições falhas ou recusadas não são cobradas.

Sua chave está a um formulário de distância

Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.