Base de coñecemento / desenvolvedores

API visión xeral

Os modelos, xeradores e balance que usa na aplicación, a partir do seu propio código.A API fala os formatos OpenAI e Anthropic, polo que a maioría das ferramentas e SDKs funcionan cambiando unha URL base e unha clave.

Esta páxina está traducida por máquina para maior comodidade. O orixinal en inglés é a versión que se aplica.

O que é o lume

Unha API HTTP nymbot.ai que responde ás mesmas solicitudes que un cliente OpenAI ou Anthropic xa envía.

• Chat Complementos, o Resposta ao lume e Mensaxes antropolóxicas, con streaming, ferramentas, imaxes, razoamento e busca web, para cada modelo no Catálogo e para o propio auto-routing de Nymbot.
• Imaxes, Vídeo, Discurso, Transcrición e Embaixadas.
• O teu equilibrio, Xogos de Lightning Top-ups, Top-ups automáticos da túa carteira e a HistoriaEditar do que custa cada solicitude.

que se pagan dos mesmos equilibrios Non hai subscrición nin permiso gratuíto na API: cada solicitude é pagada a partir de créditos que adquiriu.

O que a API non fai é engadir nada do propio Nymbot.As súas mensaxes van ao modelo mentres as enviou: ningún sistema de Nymbot, ningunha memoria, ningunha data ou linguaxe.O que vén de volta é a resposta do modelo e unha nota do que custa.

URLs de base

Todos os puntos finais viven baixo /api/v1/Un camiño descoñecido regresa 404 e un camiño coñecido chamado co método incorrecto volve 405Tanto como JSON.

A API responde ás solicitudes cruzadas de calquera sitio, de xeito que unha páxina do navegador poida chamalo.Todo o que envíe a un navegador pode ser lido por quen o abra, porén, só faga iso cunha clave que teña un pequeno CabezaOs puntos finais asinados co seu nim (chaves, resumo da conta, NWC auto-top-up e reembolso de rescate) son a excepción: nun navegador só responden aos sitios propios de Nymbot. Solicitacións de conta.

Enviar cada corpo JSON con Content-Type: application/jsonCalquera outro tipo é rexeitado 415, polo tanto, unha forma HTML simple ou un text/plain petición doutro sitio non pode chegar á API. Con cURL, pase -H "Content-Type: application/json" Xunto con -d.

chaves de lume

As chaves están feitas na aplicación.Open fogueira na barra lateral da aplicación web, ou no menú en Android e iOS, e toque Crear unha chaveDálle un nome e, se o desexa, unha copia e unha data de caducidade.

Copia-lo nun lugar seguro antes de pechar a folla: Nymbot só garda unha pegada da mesma, polo que non pode mostralo de novo.

Unha chave parece sk-nymbot- seguido de 43 letras, díxitos, diagramas e subtítulos.A aplicación lista cada clave polo seu nome e unha pequena peza como sk-nymbot-Qm7x…c2Lw.

• Unha chave pertence á túa ninfa. Gasta o seu saldo, e só o seu nim pode facelo, cambialo ou revogalo.Quen teña a clave pode gastalo, así que trátalo como un contrasinal.
• Os xogos están en sats. Unha clave pode ter un límite de gasto, e o límite pode ser redefinido todos os días, cada semana (luns) ou cada mes (o primeiro), ás 00:00 UTC. Conta ambos os saldos, un crédito estándar como 10 sats e un crédito Pro como 100, polo que significa o mesmo no que o saldo unha solicitude gasta. Antes de que unha solicitude funcione, o máximo que podería custar (arredondado ata créditos enteiros) se establece contra o que queda do límite. 403 key_limit_reached, aínda que a resposta viñese debaixo do cap; o erro di canto queda e cando o cap reseta. max_tokens Unha solicitude cobra o que realmente custa e que conta contra o cap, polo que se o provedor reporta máis tokens do que foron postos de lado, a última solicitude que se encaixa pode levar a clave un pouco máis aló do seu cap; o seguinte é rexeitado.
• Un capó gastado só detén o gasto. Unha clave na súa capa aínda pode comprobar o saldo, ler o seu historial, listar modelos, contar tokens, top-up e comprobar un vídeo que xa comezou.
• Expiry é opcional. Despois da data que establece, a clave deixa de funcionar.
• A revogación é inmediata e definitiva. Unha clave revogada falla a súa seguinte solicitude. Permanece na lista, marcada revogada, polo que o seu historial de gastos aínda ten sentido.
• Pode ter ata 25 teclas activas, cada unha co seu propio nome. Cambiar o período de restauración dunha clave comeza un novo período desde cero.

A mesma folla mostra o gasto de cada clave neste período e en total, cando foi usado por última vez, tanto os seus saldos como as súas solicitudes de API recentes. Xestión de chaves.

Autenticación dunha solicitude

Envíe a clave en calquera destes encabezados. Son equivalentes, polo que use o que o seu cliente envíe por defecto:

Devolucións de chaves perdidas, descoñecidas, revocadas ou expiradas 401Aínda que o código missing_api_key, invalid_api_key, revoked_api_key ou expired_api_keyA listaxe de modelos, modelos de audio e voces, e métodos de pagamento non precisa de chave.

As imaxes, o vídeo, o discurso, a transcrición e as incorporacións tamén se poden pagar por unha solicitude á vez a través de Lightning sen ningunha clave: envíe a solicitude sen unha e pague a factura no 402 Resposta: Vexa Pagar por solicitude sen unha chave.

A xestión de chaves, o resumo da conta e os top-ups automáticos son a excepción: toman unha sinatura do seu nim en lugar dunha clave, polo que unha chave vazada non pode facer máis chaves. Solicitacións de conta.

A túa primeira petición

Poñer a clave nunha variable ambiental e, a continuación, preguntar a un modelo algo. 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 propio enrutamento de Nymbot, pagado a partir do saldo estándar. anthropic/claude-sonnet-5, para usar ese modelo do Pro balance. Listaxe de modelos cada unha das id.

Canto custa unha solicitude

A API factura exactamente como a aplicación fai.

• Que equilibrio nymbot/auto Gasta o estándar balance (10 sats un crédito). Cada outro modelo de chat gasta o Pro O xerador de imaxes estándar e a voz estándar gastan créditos estándar; cada outro xerador gasta Pro. As incorporacións gastan créditos estándar. A transcrición gasta créditos estándar cando o saldo estándar pode cubrilo, e os créditos Pro doutro xeito. A lista de modelos di que o saldo cada modelo gasta.
• Canto máis. Unha solicitude de chat é medida nos tokens que o modelo realmente leu e escribiu, ás taxas publicadas do provedor. Ese prezo ten unha taxa de 5% engadida e despois multiplícase por 1,5, polo que paga 1.575 veces o prezo da lista do provedor. Convértese en sats ao prezo en vivo Bitcoin e cobra en milésimas dun crédito. As imaxes pro, vídeo e voz son prezadas por xeración, por segundo ou por personaxe, e a transcrición por segundo de audio, coa mesma taxa e marxe. A imaxe estándar é un plano 5 créditos estándar e a voz estándar un plano 3.
• O mínimo . Cada solicitude medida que executa custa polo menos 0,05 crédito: metade do saldo estándar, 5 do Pro.
• Manteña e despois sitúase. Antes de executar unha solicitude, o máis que pode custar é mantido do seu saldo, baseado no que enviou e o máis tokens que pode escribir. O texto fóra do ASCII común está dimensionado a partir dos seus bytes UTF-8, e os díxitos ASCII e puntuación contan como un token cada un, polo que o texto en calquera script, código e números son mantidos por completo. O hold é en créditos enteiros, polo menos un, polo que calquera solicitude necesita polo menos 10 sats libres no saldo estándar ou 100 sats en Pro para comezar. Só o custo real é cobrado; o resto é liberado cando remata. Unha solicitude longa mantén a súa posesión mentres estea en execución; se os créditos mantidos deixan de estar dispoñibles de todos os xeitos, un fluxo deténse cun 402 insufficient_balance Se o custo real é máis do que o saldo pode pagar, o saldo enteiro é tomado, o resto débese (owed_sats Na súa nymbot Obxecto, e un saldo negativo). O que se debe é pagado primeiro dos créditos seguintes que alcanzan ese saldo. Ata que se paga, nada nese saldo pode ser gastado: non pola API, respostas na aplicación, unha transferencia ou un agasallo.
• Non hai crédito suficiente. Se o saldo non pode cubrir a posesión, a solicitude é rexeitada con 402 O erro di que saldo é curto, cantos lotes a solicitude necesita e cantos son libres. max_tokens Significa unha mancha máis pequena.
• os fracasos. Unha solicitude que fracasou non custa nada, a menos que o provedor faga unha factura polo traballo que fixo antes de fracasar, ou unha busca na web ou o servizo. nymbot/auto A verificación de tarefas xa estaba en execución; entón é o que pagas, polo menos 0.05 crédito. Un fluxo que cortas cobra polos tokens que informa o provedor: Nymbot segue lendo o fluxo do provedor ata 25 segundos despois de deixar para obter esa conta.
• Busca web Custa $ 0,008 unha busca, convertida en sats, cada vez que unha busca foi executada, se o modelo entón responde ou falla.

Cada resposta di o que custa. respostas JSON levan unha nymbot obxecto co saldo do que se pagou, o cargo en créditos e sats, e o que queda:

Obxecto de custo

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

As respostas pagadas tamén levan estes encabezados, que é onde buscar o custo dunha resposta que non é JSON, como o discurso:

As taxas por millón de tokens, xa incluíndo a taxa e a marxe, están no Listaxe de modelos en dólares e en taxas, e en A táboa de prezosSe o prezo de Bitcoin non se pode ler, regresan as solicitudes pagadas 503 price_unavailable con Retry-After: 60 en vez de adiviñar.

Erros

Cada erro ten a mesma forma, unha que os clientes de OpenAI xa comprenden. code é un nome estable co que podes coincidir; message É para a xente e pode cambiar.

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
  }
}

Dúas excepcións:

• /api/v1/messages respostas no formato de erro de Anthropic, xa que é o que analizan os clientes de Anthropic: {"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).
• Unha solicitude de transmisión que falle antes do seu primeiro byte recibe un erro JSON ordinario co estado anterior, non un fluxo de eventos.

As mensaxes de erro nunca conteñen os detalles internos doutro servizo.O propio erro dun provedor é reordenado antes de que chegue a vostede.

Limitacións

Unha ligazón a unha imaxe debe apuntar a un anfitrión público: un enderezo nunha rede privada ou local, ou nos sitios propios de Nymbot, é rexeitado.

O que o lume pode ver

A API non é privada na forma en que as aplicacións son, e vale a pena ser exactos sobre como.

• Non está cifrado de extremo a extremo. Nas aplicacións, unha mensaxe está selada no seu dispositivo para as teclas que só Nymbot mantén e viaxa como un Xogo WrapUnha solicitude de API é HTTPS ordinario: está cifrada no camiño a Nymbot, e o servidor de Nymbot leuna no claro para manexalo.
• As solicitudes e respostas non se almacenan. O que se mantén é a factura: para cada solicitude o tempo, modelo, tipo, token conta, custo, saldo, clave e se logrou, durante 90 días, que é o que Queremos historia Un rexistro de uso da mesma solicitude (hora, tipo, modelo, conta de tokens, custo, duración e se usou a busca web ou logrou) tamén se mantén durante 90 días, xunto coa propia aplicación.
• Todo o demais mantido para unha ninfa é pequeno e listado aquí. chaves de lume son almacenados como un hash, nunca a clave, co seu nome, unha pista curta, límite de gasto, período de restauración, expiración e cando foron feitos e usados por última vez; só se conservan as últimas 50 claves revocadas. Top-up automático As solicitudes pagadas por chamada só deixan un hash de pago de Lightning durante 7 días e un token de reembolso hashado durante 30 días, vinculado a ningún nym.
• Descargar a app Eliminar. A Instalacións WIPE revoga e elimina cada clave de API, e elimina o historial de consultas, rexistros de uso, conexión de carteira e traballos de vídeo.
• O provedor do modelo ve a túa solicitudeOs modelos de catálogo funcionan nos seus creadores; as rutas estándar e as incorporacións funcionan en Cloudflare.
• Os medios xerados son públicos. As imaxes e os vídeos entregados como ligazóns son cargados a hospedes de ficheiros públicos de Blossom, onde o enderezo dun ficheiro é o seu hash.Quen teña a ligazón pode abri-lo e Nymbot non pode baixalo de novo. b64_json e unha imaxe xerada volve na resposta e nunca se carga.
• Así son as imaxes que dá un xerador. Unha imaxe que subiches Editar, ou enviar como a data: URL dun xerador image_url, é cargado a un anfitrión público Blossom primeiro para que o xerador poida recuperalo, e o mesmo se aplica a el. https:// As imaxes nunha solicitude de chat van ao provedor do modelo, non a Blossom.
• Unha clave está ligada ao seu nym. Todo o que unha clave gasta vén do saldo do seu nim, polo que o uso da API non é AnónimoSe queres que o uso da API se manteña separado do teu nym cotián, fai as chaves dun nym separado co seu propio equilibrio.

Se precisa a protección das aplicacións, use as aplicacións.A API é para cando precisa os modelos nas súas propias ferramentas.

Cada punto final

“Nym” significa unha solicitude asinada pola súa clave Nostr, descrita en Solicitacións de contaPara as ferramentas que xa falan destes formatos, consulte Ferramentas e SDK, e para axentes de codificación como Claude Code, Codex e Cline, véxase Ferramentas de codificación.