Base de conhecimento / Desenvolvedores

API Visão Geral

Os modelos, geradores e balanços que você usa no aplicativo, a partir do seu próprio código.A API fala os formatos OpenAI e Anthropic, então a maioria das ferramentas e SDKs funcionam alterando um URL de base e uma chave.

Esta página foi traduzida automaticamente por conveniência. O original em inglês é a versão aplicável.

O que é o Fogo

Uma API HTTP nymbot.ai que responde aos mesmos pedidos que um cliente OpenAI ou Anthropic já envia.

• Chat Completo, o Reações a Fogo e Mensagens Antropológicas, com streaming, ferramentas, imagens, raciocínio e pesquisa na web, para cada modelo no Catálogo e para o próprio auto-routing do Nymbot.
• Imagens, Vídeo, Discurso, Transcrição e Embaixadores.
• Seu equilíbrio, Lançamento de Lightning Top-ups, Top-ups automáticos da sua carteira e a História quanto custa cada pedido.

É pago pelos mesmos dois Equilíbrio Como o aplicativo, aos mesmos preços.Não há subscrição e nenhuma concessão gratuita na API: cada pedido é pago a partir de créditos que você comprou.

O que a API não faz é adicionar nada do próprio Nymbot. Suas mensagens vão para o modelo quando você as enviou: nenhum sistema Nymbot prompt, nenhuma memória, nenhuma data ou sugestões de idioma.

URLs de base

Todos os endpoints vivem /api/v1/Um caminho desconhecido retorna 404 e um caminho conhecido chamado com o método errado retorna 405Ambos são JSON.

A API responde às solicitações de origem cruzada de qualquer site, de modo que uma página do navegador possa chamá-la.Tudo o que você enviar para um navegador pode ser lido por quem o abre, no entanto, então faça isso apenas com uma chave que tenha um pequeno CapãoOs endpoints assinados com o seu nym (chaves, resumo da conta, NWC auto-top-up e resgate de reembolso) são a exceção: em um navegador eles respondem apenas aos sites próprios do Nymbot. Solicitação de assinatura de contas.

Envie cada corpo JSON com Content-Type: application/jsonQualquer outro tipo é recusado com 415, então uma forma simples de HTML ou um text/plain solicitação de outro site não pode alcançar a API. Com o cURL, -H "Content-Type: application/json" Juntamente com -d.

Chaves de fogo

As chaves são feitas no app. Fogo na barra lateral do aplicativo web, ou no menu no Android e iOS, e toque Criar uma chaveDê-lhe um nome e, se desejar, uma capa e uma data de expiração.

A chave é mostrada uma vez.Copiá-la em algum lugar seguro antes de fechar a folha: Nymbot mantém apenas uma impressão digital dela, para que não possa mostrá-la novamente.Uma chave perdida não pode ser recuperada; revogá-la e fazer outra.

A chave parece sk-nymbot- A aplicação lista cada chave pelo seu nome e uma pequena dica, como por exemplo: sk-nymbot-Qm7x…c2Lw.

• Uma chave pertence ao seu ninho. Ele gasta o seu saldo, e apenas o seu nim pode fazê-lo, alterá-lo ou revogá-lo.Qualquer pessoa com a chave pode gastá-lo, então trate-o como uma senha.
• As capas estão em apostas. Uma chave pode ter um limite de gastos, e o limite pode ser redefinido todos os dias, todas as semanas (lunes) ou todos os meses (primeiro), às 00:00 UTC. Conta ambos os saldos, um crédito padrão como 10 sats e um crédito Pro como 100, então significa o mesmo qualquer que seja o saldo que um pedido gasta. Antes de um pedido correr, o máximo que poderia custar (arredondado até créditos inteiros) é definido contra o que resta do limite. 403 key_limit_reached, mesmo que a resposta tenha entrado debaixo do cap; o erro diz quanto é deixado e quando o cap reseta. max_tokens Um pedido é cobrado o que realmente custa e que conta contra o cap, então se o provedor relatar mais tokens do que foram colocados de lado, o último pedido que se encaixa pode levar a chave um pouco além de seu cap; o próximo é então recusado.
• Um capô gasto só pára o gasto. Uma chave em seu cap ainda pode verificar o saldo, ler seu histórico, listar modelos, contar tokens, subir e verificar um vídeo que já começou.
• A expiração é opcional. Após a data definida, a chave deixa de funcionar.
• A revogação é imediata e definitiva. Uma chave revogada falha em sua próxima solicitação. ela permanece na lista, marcada revogada, então seu histórico de gastos ainda faz sentido.
• Você pode ter até 25 chaves ativas, cada uma com seu próprio nome. Alterar o período de redefinição de uma chave inicia um novo período a partir de zero.

A mesma folha mostra o gasto de cada chave neste período e, no total, quando foi usado pela última vez, ambos os seus saldos e as suas solicitações de API recentes. Gerenciamento de chaves.

Autenticação de um pedido

Envie a chave em qualquer um desses cabeçalhos. Eles são equivalentes, então use o que seu cliente envia por padrão:

Retorno de chaves perdidas, desconhecidas, revogadas ou expiradas 401Com o código missing_api_key, invalid_api_key, revoked_api_key ou expired_api_keyListar modelos, modelos de áudio e vozes, e métodos de pagamento não precisa de chave.

Imagens, vídeo, fala, transcrição e embeddings também podem ser pagos por um pedido de cada vez através do Lightning sem nenhuma chave: envie o pedido sem um e pague a fatura no 402 Resposta - Veja Pagamento por solicitação sem chave.

O gerenciamento de chaves, o resumo da conta e os top-ups automáticos são a exceção: eles tomam uma assinatura do seu nim em vez de uma chave, então uma chave vazada não pode fazer mais chaves. Solicitação de assinatura de contas.

O seu primeiro pedido

Coloque a chave em uma variável de ambiente e, em seguida, peça algo a um modelo. NYMBOT_API_KEY.

cURL

export NYMBOT_API_KEY="sk-nymbot-..."

curl https://nymbot.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $NYMBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nymbot/auto",
    "messages": [{"role": "user", "content": "What is a Lightning invoice?"}]
  }'

Python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://nymbot.ai/api/v1",
    api_key=os.environ["NYMBOT_API_KEY"],
)

reply = client.chat.completions.create(
    model="nymbot/auto",
    messages=[{"role": "user", "content": "What is a Lightning invoice?"}],
)
print(reply.choices[0].message.content)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://nymbot.ai/api/v1",
  apiKey: process.env.NYMBOT_API_KEY,
});

const reply = await client.chat.completions.create({
  model: "nymbot/auto",
  messages: [{ role: "user", content: "What is a Lightning invoice?" }],
});
console.log(reply.choices[0].message.content);

nymbot/auto é o próprio roteamento do Nymbot, pago a partir do saldo padrão. anthropic/claude-sonnet-5, para usar esse modelo a partir do Pro Balance. Lista de modelos Dê a cada ID.

Quanto custa um pedido

A API fatura exatamente como o aplicativo faz.

• Que equilíbrio nymbot/auto Gasta o padrão balanço (10 sats um crédito). Cada outro modelo de bate-papo gasta o Pro O gerador de imagem padrão e a voz padrão gastam créditos padrão; cada outro gerador gasta Pro. Embeddings gasta créditos padrão. Transcrição gasta créditos padrão quando o saldo padrão pode cobri-lo, e créditos Pro de outra forma. A lista de modelos diz que o saldo que cada modelo gasta.
• Quanto quanto . Um pedido de bate-papo é medido nos tokens que o modelo realmente leu e escreveu, nas taxas publicadas pelo provedor. Esse preço tem uma taxa de 5% adicionada e é então multiplicado por 1,5, então você paga 1.575 vezes o preço da lista do provedor. É convertido para sats no preço do Bitcoin ao vivo e cobrado em milésimas de um crédito. Pro imagens, vídeo e voz são preços por geração, por segundo ou por caráter, e transcrição por segundo de áudio, com a mesma taxa e margem. A imagem padrão é um plano 5 créditos padrão e a voz padrão um plano 3.
• O mínimo . Cada pedido medido que executa custa pelo menos 0,05 crédito: metade do saldo padrão, 5 apostas no Pro. Fracções de um crédito são carregadas, não arredondadas a cada vez.
• Mantenha, então fique tranquilo. Antes de um pedido ser executado, o máximo que poderia custar é mantido do seu saldo, com base no que você enviou e no máximo de tokens que ele pode escrever. O texto fora do ASCII comum é dimensionado a partir de seus bytes UTF-8, e os dígitos ASCII e a pontuação contam como um token cada, de modo que o texto em qualquer script, código e números são mantidos na íntegra. O hold é em créditos inteiros, pelo menos um, de modo que qualquer pedido precisa de pelo menos 10 sats grátis no saldo padrão ou 100 sats no Pro para começar. Somente o custo real é cobrado; o resto é liberado quando termina. Um pedido longo mantém sua posse enquanto estiver em execução; se os créditos mantidos parar de estar disponíveis de qualquer forma, um fluxo pára com um 402 insufficient_balance Se o custo real é maior do que o saldo pode pagar, o saldo inteiro é tomado, o resto é devido (owed_sats Em O nymbot Objeto, e um saldo negativo). O que é devido é pago primeiro dos créditos seguintes que atingem esse saldo. Até que seja pago, nada nesse saldo pode ser gasto: não pela API, respostas no aplicativo, uma transferência ou um presente.
• Não há crédito suficiente. Se o saldo não puder cobrir a manutenção, o pedido é recusado com 402 O erro diz qual balanço é curto, quantos sats a solicitação precisa e quantos são gratuitos. max_tokens Significa uma manutenção menor.
• dos fracassos. Um pedido que falha não custa nada, a menos que o fornecedor tenha cobrado pelo trabalho que fez antes de falhar, ou uma pesquisa na web ou o nymbot/auto Um fluxo que você corte é cobrado pelos tokens que o provedor relata: Nymbot continua a ler o fluxo do provedor por até 25 segundos depois de você sair para obter essa contagem.
• Pesquisa Web Custa $0.008 uma pesquisa, convertida em sats, sempre que uma pesquisa foi executada, se o modelo então responde ou falha.

Cada resposta diz quanto custa. respostas JSON carregam uma nymbot objeto com o saldo a partir do qual foi pago, o encargo em créditos e sats, e o que resta:

O custo do objeto

"nymbot": {
  "balance": "pro",
  "charged_credits": 0.162,
  "charged_sats": 16.2,
  "balance_credits": 412.425,
  "balance_sats": 41242.5
}

As respostas pagas também carregam esses cabeçalhos, que são onde procurar o custo de uma resposta que não é JSON, como a fala:

As taxas por milhão de tokens, já incluindo a taxa e a margem, estão na Lista de modelos em dólares e taxas, e em A folha de preçosSe o preço do Bitcoin não puder ser lido, os pedidos pagos retornam 503 price_unavailable com Retry-After: 60 Em vez de adivinhar.

Erros

Cada erro tem a mesma forma, uma que os clientes da OpenAI já entendem. code é um nome estável que você pode combinar; message É para as pessoas e pode mudar.

Corpo errado

{
  "error": {
    "message": "This request needs up to 200 sats (2 credits) on your Pro balance, and 40 sats are free. Catalog models spend the Pro balance. Top up in the Nymbot app or with POST /api/v1/topup/create/btc-lightning.",
    "type": "insufficient_quota",
    "code": "insufficient_balance",
    "param": null,
    "balance": "pro",
    "required_sats": 200,
    "balance_sats": 40
  }
}

Duas exceções:

• /api/v1/messages respostas no formato de erro da Anthropic, uma vez que é isso que os clientes da Anthropic analisam: {"type": "error", "error": {"type": "authentication_error", "message": "…"}}O tipo segue o status: invalid_request_error, authentication_error, billing_error (402), permission_error, not_found_error, request_too_large, rate_limit_error, api_error ou overloaded_error (503).
• Uma solicitação de streaming que falha antes de seu primeiro byte recebe um erro JSON comum com o status acima, não um fluxo de eventos.

As mensagens de erro nunca contêm detalhes internos de outro serviço.O próprio erro de um provedor é reordenado antes de chegar a você.

Limite

Um link para uma imagem deve apontar para um host público: um endereço em uma rede privada ou local, ou em sites próprios do Nymbot, é recusado.

O que a fogueira pode ver

A API não é privada na forma como os aplicativos são, e vale a pena ser exato sobre como.

• Não é end-to-end criptografado Nos aplicativos, uma mensagem é selada no seu dispositivo para chaves apenas Nymbot detém e viaja como um Apresentação WrapUm pedido de API é HTTPS comum: é criptografado no caminho para o Nymbot, e o servidor do Nymbot lê-o no claro para lidar com ele.
• Os pedidos e respostas não são armazenados. O que é mantido é a fatura: para cada solicitação o tempo, modelo, tipo, contagem de token, custo, saldo, chave e se ele conseguiu, por 90 dias, que é o que Queremos História Um registro de uso do mesmo pedido (hora, tipo, modelo, contagem de tokens, custo, duração e se ele usou a pesquisa na web ou foi bem sucedido) também é mantido por 90 dias, juntamente com o próprio aplicativo.
• Tudo o resto mantido para um ninho é pequeno e listado aqui. Chaves de fogo são armazenados como um hash, nunca a chave, com o seu nome, uma pista curta, cap de gasto, período de reset, expiração e quando eles foram feitos e usados pela última vez; apenas as mais recentes 50 chaves revogadas são mantidas. Top-up automático As solicitações pagas por chamada deixam apenas um hash de pagamento do Lightning por 7 dias e um token de reembolso hashado por 30 dias, ligado a nenhum nym.
• Apagar o app o remove. A Dispositivo Wipe revoga e exclui cada chave da API, e exclui o histórico de consultas, registros de uso, conexão de carteira e trabalhos de vídeo.
• O fornecedor do modelo vê o seu pedidoOs modelos de catálogo são executados em seus criadores; rotas e embeddings padrão são executados no Cloudflare.
• A mídia gerada é pública. Imagens e vídeos entregues como links são carregados para hospedes de arquivos públicos Blossom, onde o endereço de um arquivo é seu hash. Qualquer pessoa com o link pode abri-lo, e o Nymbot não pode baixá-lo novamente. b64_json e uma imagem gerada retorna na resposta e nunca é carregada.
• Assim são as imagens que você dá a um gerador. Uma imagem que você upload para Edit, ou enviar como a data: URL em um gerador image_url, é carregado para um servidor público Blossom primeiro para que o gerador possa recuperá-lo, e o mesmo se aplica a ele. https:// As imagens em um pedido de bate-papo vão para o provedor do modelo, não para Blossom.
• Uma chave está ligada ao seu nym. Tudo o que uma chave gasta vem do saldo do seu nim, então o uso da API não é AnônimoSe você quiser que o uso da API seja mantido separado do seu nym diário, faça as chaves de um nym separado com seu próprio equilíbrio.

Se você precisar da proteção dos aplicativos, use os aplicativos.A API é para quando você precisa dos modelos em suas próprias ferramentas.

Todos os Endpoints

“Nym” significa uma solicitação assinada pela sua chave Nostr, descrita em Solicitação de assinatura de contasPara ferramentas que já falam esses formatos, veja Ferramentas e SDKs, e para agentes de codificação como Claude Code, Codex e Cline, veja Ferramentas de codificação.