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_tokensmuito 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.
