Kunnskapsgrunnlag / Utviklere

Brann overblikk

De modellene, generatorene og balanse du bruker i appen, fra din egen kode. API snakker OpenAI og Anthropic formater, så de fleste verktøy og SDKer fungerer ved å endre en base URL og en nøkkel.

Denne siden er maskinoversatt for enkelhets skyld. Den engelske originalen er versjonen som gjelder.

Hva er brann

En HTTP API på nymbot.ai som svarer på de samme forespørslene som en OpenAI eller Anthropic-klient allerede sender.

• Chat fullføringerog den Svar fra API og Antropiske budskap, med streaming, verktøy, bilder, resonnement og nettsøk, for hver modell i Kataloger og for Nymbots egen auto-routing.
• bilder, Videoer, taler, transkripsjon og Embedded.
• Din Balansen, Lightning topp-up, Automatisk topp-up fra lommeboken din og a Historie hva hver forespørsel koster.

Betales fra de samme to Balanseringer Det er ingen abonnement og ingen gratis tillatelse på API: hver forespørsel betales fra kreditter du kjøpte.

Det API ikke gjør er å legge til noe av Nymbots egen. Meldingene dine går til modellen som du sendte dem: ingen Nymbots systemoppsummering, ingen minne, ingen dato eller språk hint.

Grunnleggende URLs

Hver ende lever under /api/v1/En ukjent vei tilbake 404 og en kjent vei kalt med feil metode returnerer 405Begge deler er JSON.

API-en svarer på kryssopprinnelsesforespørsler fra et hvilket som helst nettsted, slik at en nettleserside kan ringe den. HodeEndpoengene som er signert med nym (nøkler, kontooppsummering, NWC auto-top-up og refund-redemption) er unntaket: i en nettleser svarer de bare på Nymbots egne nettsteder. Signering av konto forespørsler.

Send hver JSON-kropp med Content-Type: application/jsonEnhver annen type er avvist med 415, slik at en enkel HTML-form eller en text/plain forespørsel fra et annet nettsted kan ikke nå API. Med cURL, passere -H "Content-Type: application/json" Sammen med -d.

Brannnøkler

Nøklene er laget i appen.Open ild i sidebaren i webappen, eller i menyen på Android og iOS, og trykk Opprette nøkkelGi det et navn og, hvis du vil, en kappe og en utløpsdato.

Nymbot beholder bare et fingeravtrykk av det, så det ikke kan vise det til deg igjen. En tapt nøkkel kan ikke gjenopprettes; tilbakekalle den og lage en annen.

Nøkkelen ser ut som sk-nymbot- etterfulgt av 43 bokstaver, tall, dash og underscore. appen lister hver nøkkel etter navn og en kort hint som sk-nymbot-Qm7x…c2Lw.

• En nøkkel tilhører din nym. Det bruker din balanse, og bare din nym kan lage, endre eller trekke den tilbake.
• Caps er i sats. En nøkkel kan ha en utgiftskapasitet, og kapasiteten kan tilbakestilles hver dag, hver uke (mandag) eller hver måned (første), ved 00:00 UTC. Den teller begge saldoer, en standardkreditt som 10 sats og en Pro-kreditt som 100, så det betyr det samme uansett hvilken saldo en forespørsel bruker. Før en forespørsel kjører, er det maksimale det kan koste (rundet opp til hele kreditter) satt mot det som er igjen av kapasiteten. 403 key_limit_reached, selv om svaret ville ha kommet inn under kappen; feilen forteller hvor mye som er igjen og når kappen tilbakestilles. max_tokens En forespørsel blir belastet hva det faktisk koster og som teller mot cap, så hvis leverandøren rapporterer flere tokens enn ble satt til side, kan den siste forespørselen som passer ta nøkkelen litt over sin cap; den neste blir deretter avvist.
• En brukt kappe stopper bare utgiftene. En nøkkel ved kappen kan fortsatt sjekke saldoen, lese dens historie, liste modeller, telle tokens, topp opp og sjekke på en video den allerede har startet.
• Utløpet er valgfritt. Etter datoen du har angitt, slutter nøkkelen å fungere.
• Oppsigelse er umiddelbar og endelig. En tilbakekalt nøkkel feiler sin neste forespørsel.Den forblir i listen, merket tilbakekalt, så utgiftshistorikken er fortsatt fornuftig.
• Du kan ha opptil 25 aktive nøkler, hver med sitt eget navn.

Det samme arket viser hver nøkkel utgifter denne perioden og i alt, når den ble sist brukt, både dine saldoer, og dine nylige API-forespørsler. Styring av nøkler.

Autentisering av en forespørsel

Send nøkkelen i noen av disse overskriftene.De er tilsvarende, så bruk hva klienten din sender som standard:

En manglende, ukjent, tilbakekalt eller utløpt nøkkel returnerer 401Med koden missing_api_key, invalid_api_key, revoked_api_key eller expired_api_keyListing modeller, lydmodeller og stemmer, og betalingsmetoder trenger ingen nøkkel.

Bilder, video, tale, transkripsjon og innebygging kan også betales for én forespørsel om gangen over Lightning uten nøkkel i det hele tatt: send forespørselen uten en og betal fakturaen i 402 Svar: Se Betal på forespørsel uten nøkkel.

Nøkkeladministrasjon, kontooppsummering og automatiske top-ups er unntaket: de tar en signatur fra nym i stedet for en nøkkel, slik at en lekket nøkkel ikke kan lage flere nøkler. Signering av konto forespørsler.

Din første forespørsel

Sett nøkkelen i en miljøvariabel, og spør deretter en modell om noe. 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 er Nymbots egen ruting, betalt fra standardbalansen. Sett et katalogmodell-id der i stedet, for eksempel anthropic/claude-sonnet-5, for å bruke denne modellen fra Pro-balansen. Liste over modeller Gi hver enkelt id.

Hva koster en forespørsel

API fakturerer nøyaktig slik appen gjør.

• Og hvilken balanse. nymbot/auto Bruker den Standarden balanse (10 sats en kreditt). Hver annen chat-modell bruker Pro balanse (100 sats en kreditt). Standard bildegenerator og standard stemme bruker standard kreditter; hver annen generator bruker Pro. Embeddings bruker standard kreditter. Transcription bruker standard kreditter når standard balanse kan dekke det, og Pro kreditter ellers. Modelllisten forteller hvilken balanse hver modell bruker.
• Hvor mye . En chat-forespørsel måles på tokens som modellen faktisk leser og skriver, ved leverandørens publiserte priser. Denne prisen har en 5% gebyr lagt til og multipliseres deretter med 1,5, så du betaler 1,575 ganger leverandørens listepris. Den konverteres til sats på live Bitcoin-prisen og belastes i tusendeler av en kreditt. Pro bilder, video og tale er prissatt per generasjon, per sekund eller per tegn, og transkripsjon per sekund av lyd, med samme gebyr og margin.
• Og det minste. Hver målt forespørsel som kjører koster minst 0,05 kreditt: halvparten satt på standardbalansen, 5 satser på Pro.
• Hold deretter og sett deg ned. Før en forespørsel kjører, det meste det kan koste holdes fra saldoen din, basert på hva du sendte og de fleste tokens det kan skrive. Tekst utenfor vanlig ASCII er størrelsen fra sine UTF-8 bytes, og ASCII-siffer og punktering telle som en token hver, så tekst i ethvert skript, kode og tall holdes for fullt. Holdet er i hele kreditter, minst en, så enhver forespørsel trenger minst 10 sats gratis på standard saldoen eller 100 sats på Pro for å starte. Bare den faktiske kostnaden belastes; resten frigjøres når den er ferdig. En lang forespørsel holder sitt hold så lenge den kjører; hvis de holdt kreditter stopper å være tilgjengelig uansett, stopper en strøm med en 402 insufficient_balance Hvis den faktiske kostnaden er mer enn saldoen kan betale, blir hele saldoen tatt, resten er gjeld (owed_sats I den nymbot objekt, og en negativ saldo). Det som skyldes betales først ut av de neste kreditter som når den saldoen. Inntil det er betalt, kan ingenting på den saldoen brukes: ikke av API, svarer i appen, en overføring eller en gave.
• Ikke nok kreditt Hvis saldoen ikke kan dekke holdet, blir forespørselen avslått med 402 Feilen forteller hvilken balanse som er kort, hvor mange satser forespørselen trenger og hvor mange er gratis. max_tokens Det betyr mindre hold.
• og svikt. En forespørsel som mislykkes koster ingenting, med mindre leverandøren fakturerte for arbeidet det gjorde før det mislykkes, eller en nettsøk eller nymbot/auto En strøm du kutter av blir belastet for tokens som leverandøren rapporterer: Nymbot fortsetter å lese leverandørens strøm i opptil 25 sekunder etter at du forlater for å få den telle.
• Web søk koster $ 0,008 en søk, konvertert til sats, hver gang en søk ble kjørt, enten modellen da svarer eller mislykkes.

Hvert svar sier hva det koster. JSON-svar bærer en nymbot objekt med saldoen det ble betalt fra, avgiften i kreditter og satser, og hva som er igjen:

Kostnadsobjektet

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

Betalte svar har også disse overskriftene, som er hvor du kan se etter kostnaden for et svar som ikke er JSON, for eksempel tale:

Priser per million tokens, allerede inkludert gebyr og margin, er i Liste over modeller i dollar og sats, og på PrislistenHvis Bitcoin-prisen ikke kan leses, returneres betalte forespørsler 503 price_unavailable med Retry-After: 60 I stedet for å gjette.

Feilene

Hver feil har samme form, en som OpenAI-klienter allerede forstår. code er et stabilt navn du kan matche; message Det er for folk og kan forandre seg.

Feil kropp

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

To unntak er:

• /api/v1/messages svar i Anthropics feilformat, siden det er det Anthropic-klienter analyserer: {"type": "error", "error": {"type": "authentication_error", "message": "…"}}Typen følger statusen: invalid_request_error, authentication_error, billing_error (402), permission_error, not_found_error, request_too_large, rate_limit_error, api_error eller overloaded_error (503).
• En streamingforespørsel som mislykkes før sin første byte, får en vanlig JSON-feil med statusen ovenfor, ikke en hendelsesstrøm.

Feilmeldinger inneholder aldri interne detaljer om en annen tjeneste.En leverandørs egen feil blir omordnet før den når deg.

Grenser

En kobling til et bilde må peke til en offentlig vert: en adresse på et privat eller lokalt nettverk, eller på Nymbots egne nettsteder, blir avvist.

Hva brannen kan se

API er ikke privat på den måten appene er, og det er verdt å være nøyaktig om hvordan.

• Det er ikke end-to-end kryptert. I appene er en melding forseglet på enheten til nøkler bare Nymbot holder og reiser som en Gave WrapEn API-forespørsel er vanlig HTTPS: den er kryptert på vei til Nymbot, og Nymbots server leser den i klar for å håndtere den.
• Prompter og svar lagres ikke. Det som holdes er regningen: for hver forespørsel tid, modell, type, token teller, kostnad, balanse, nøkkel og om det lyktes, i 90 dager, som er hva Ønsker historie En brukspost av samme forespørsel (tid, type, modell, token teller, kostnad, varighet og om det brukte web-søk eller lyktes) blir også holdt i 90 dager, sammen med appens egen.
• Alt annet holdt for en nym er liten og oppført her. Brannnøkler er lagret som en hash, aldri nøkkelen, med sitt navn, en kort hint, utgiftskapasitet, tilbakestillingsperiode, utløpsdato og når de ble laget og sist brukt; bare de nyeste 50 tilbakekalte nøklene blir beholdt. Automatisk top-up Video jobber holdes i 24 timer. forespørsler betalt per samtale etterlater bare en Lightning betaling hash i 7 dager og en hashed refund token i 30 dager, knyttet til ingen nym. gebyrer en balanse ikke kunne dekke holdes som skyldte inntil en top-up betaler dem.
• Ved å slette appen sletter du den. A Utstyr Wipe tilbakekaller og sletter hver API-nøkkel, og sletter spørringshistorikk, bruksrekord, lommebokforbindelse og videojobber.
• Modellenes leverandør ser forespørselen dinKatalogmodeller kjører på sine produsenter; standard ruter og innebygging kjører på Cloudflare.
• Genererte medier er offentlige. Bilder og videoer levert som koblinger lastes opp til offentlige Blossom-filverter, hvor en fils adresse er dens hash. Alle med koblingen kan åpne den, og Nymbot kan ikke ta den ned igjen. b64_json og et generert bilde kommer tilbake i svaret og lastes aldri opp.
• Slik er bildene du gir en generator. Et bilde du laster opp til Edit, eller send som a data: URL i en generator image_url, lastes opp til en offentlig Blossom-verten først slik at generatoren kan hente den, og det samme gjelder for den. https:// Bilder i en chat-forespørsel går til modellens leverandør, ikke til Blossom.
• En nøkkel er koblet til nym. Alt en nøkkel bruker kommer fra din nym balanse, så API bruk er ikke AnonymeHvis du vil at API-bruken skal holdes unna din daglige nym, gjør nøklene fra en egen nym med sin egen balanse.

Hvis du trenger beskyttelse av appene, bruk appene. API er for når du trenger modellene i dine egne verktøy.

Hvert endepunkt

“Nym” betyr en forespørsel signert av din Nostr-nøkkel, beskrevet i Signering av konto forespørslerFor verktøy som allerede snakker disse formatene, se Verktøy og SDK, og for koding agenter som Claude Code, Codex og Cline, se Kodingsverktøy.