Kunskapsbas / Utvecklare

API Översikt

De modeller, generatorer och balans du använder i appen, från din egen kod. API talar OpenAI och Anthropic format, så de flesta verktyg och SDK fungerar genom att ändra en bas-URL och en nyckel.

Den här sidan är maskinöversatt för enkelhetens skull. Det engelska originalet är den version som gäller.

Vad är elden

En HTTP API på nymbot.ai som svarar på samma förfrågningar som en OpenAI- eller Anthropic-klient redan skickar.

• Chat kompletteraroch den Svar från API och Antropiska budskap, med strömning, verktyg, bilder, resonemang och webbsökning, för varje modell i Katalogen och för Nymbots egen auto-routing.
• bilderna, Videor, talet, Transkription och Inbäddningar.
• Din Balansera, Blinkande topp-ups, Automatisk toppup från din plånbok och a Historik hur mycket varje förfrågan kostar.

Det betalas från samma två Balansera Det finns ingen prenumeration och ingen gratis tillägg på API: varje begäran betalas från krediter du köpt.

Vad API inte gör är att lägga till något av Nymbots egen. Dina meddelanden går till modellen när du skickade dem: ingen Nymbots systemkommando, inget minne, inget datum eller språktips.

Grundläggande URL

Varje slutpunkt lever under /api/v1/En okänd väg återvänder 404 och en känd väg som kallas med fel metod returnerar 405Båda är JSON.

API svarar på kors-ursprung förfrågningar från vilken webbplats som helst, så en webbläsarsida kan ringa den. Allt du skickar till en webbläsare kan läsas av vem som helst som öppnar den, så gör det bara med en nyckel som har en liten huvudDe slutpunkter som undertecknas med din nym (nycklar, kontosammanfattning, NWC auto-top-up och återbetalning) är undantaget: i en webbläsare svarar de bara på Nymbots egna webbplatser. Signera konto förfrågningar.

Skicka varje JSON-kropp med Content-Type: application/jsonAlla andra typer av avvisas med 415, så en enkel HTML-form eller en text/plain begäran från en annan webbplats kan inte nå API. Med cURL, passera -H "Content-Type: application/json" Tillsammans med -d.

Brandnycklar

Nycklar görs i appen. öppen elden i sidopanelen i webbappen eller i menyn på Android och iOS och tryck på Skapa nyckelGe det ett namn och, om du vill, ett lock och ett utgångsdatum.

Nyckeln visas en gång. Kopiera den någonstans säkert innan du stänger arket: Nymbot behåller bara ett fingeravtryck av det, så det kan inte visa det till dig igen.

En nyckel ser ut som sk-nymbot- följt av 43 bokstäver, siffror, tabeller och underpunkter. Appen listar varje nyckel med sitt namn och en kort ledtråd som sk-nymbot-Qm7x…c2Lw.

• En nyckel tillhör din nym. Det spenderar din balans, och bara din nym kan göra, ändra eller återkalla den.
• Caps är i sats. En nyckel kan ha en utgiftskapacitet, och kapaciteten kan återställas varje dag, varje vecka (måndag) eller varje månad (den första), vid 00:00 UTC. Den räknar båda saldon, en standardkredit som 10 sats och en Pro-kredit som 100, så det betyder samma oavsett vilket saldo en begäran spenderar. Innan en begäran körs, är det högsta det kan kosta (rundat upp till hela krediter) satt mot vad som är kvar av kapaciteten. 403 key_limit_reached, även om svaret skulle ha kommit in under locket; felet säger hur mycket som är kvar och när locket återställs. max_tokens En begäran debiteras vad den faktiskt kostar och det räknas mot taket, så om leverantören rapporterar fler tokens än ställdes åt sidan, kan den sista begäran som passar ta nyckeln lite bortom sitt tak; nästa avvisas sedan.
• En förbrukad cap stoppar bara utgifterna. En nyckel vid sin topp kan fortfarande kontrollera saldot, läsa dess historia, lista modeller, räkna tokens, topp upp och kolla på en video som den redan har börjat.
• Expiry är valfritt. Efter det datum du anger slutar nyckeln att fungera.
• Återkallelse är omedelbar och slutgiltig. En återkallad nyckel misslyckas med sin nästa begäran. Den förblir i listan, märkt återkallad, så dess utgiftshistorik är fortfarande meningsfull.
• Du kan ha upp till 25 aktiva nycklar, var och en med sitt eget namn. Om du ändrar nyckelns återställningsperiod börjar en ny period från noll.

Samma ark visar varje nyckels utgifter den här perioden och totalt, när den senast användes, både dina balansräkningar och dina senaste API-förfrågningar. Hantera nycklar.

Autentisera en begäran

Skicka nyckeln i någon av dessa rubriker. De är likvärdiga, så använd vad din klient skickar som standard:

En saknad, okänd, återkallad eller utgången nyckel returnerar 401och med koden missing_api_key, invalid_api_key, revoked_api_key eller expired_api_keyListning av modeller, ljudmodeller och röster och betalningsmetoder behöver ingen nyckel.

Bilder, video, tal, transkription och inbäddningar kan också betalas för en begäran i taget över Lightning utan nyckel alls: skicka begäran utan en och betala fakturan i 402 Svar: Se Betala på begäran utan nyckel.

Nyckelhantering, kontosammanfattning och automatiska toppar är undantaget: de tar en signatur från din nym istället för en nyckel, så en läckt nyckel kan inte göra fler nycklar. Signera konto förfrågningar.

Din första begäran

Sätt nyckeln i en miljövariabel och fråga sedan en modell om något. 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 är Nymbots egen routing, betald från standardbalansen. Placera en katalogmodellens id där istället, till exempel anthropic/claude-sonnet-5, för att använda den modellen från Pro-balansen. Lista över modeller Ge varje id.

Vad kostar en begäran

API fakturerar precis som appen gör.

• Och vilken balans. nymbot/auto Spenderar den Standard är balans (10 sats en kredit). Varje annan chattmodell spenderar För balans (100 sats en kredit). Standardbildgenerator och standard röst spenderar standardkrediter; varje annan generator spenderar Pro. Embeddings spenderar standardkrediter. Transcription spenderar standardkrediter när standardbalansen kan täcka det, och Pro-krediter annars. Modelllistan säger vilken balans varje modell spenderar.
• Hur mycket . En chattförfrågan mäts på de tokens som modellen faktiskt läser och skriver, vid leverantörens publicerade priser. Det priset har en 5% avgift och multipliceras sedan med 1,5, så du betalar 1,575 gånger leverantörens listpris. Det konverteras till sats vid levande Bitcoin pris och debiteras i tusendelar av en kredit. Pro bilder, video och tal prissätts per generation, per sekund eller per tecken, och transkription per sekund av ljud, med samma avgift och marginal. Standardbilden är en platt 5 standardkrediter och standardröst en platt 3.
• Det minsta . Varje mätad begäran som kör kostar minst 0,05 kredit: en halv satt på standardbalansen, 5 satsar på Pro. Fraktioner av en kredit bärs över, inte avrundas varje gång.
• Håll, sedan sätta sig. Innan en begäran körs, det mesta det kan kosta hålls från ditt saldo, baserat på vad du skickar och de flesta tokens det kan skriva. Text utanför den vanliga ASCII är stor från sina UTF-8 bytes, och ASCII-siffror och punktering räknas som en token varje, så text i något skript, kod och nummer hålls för fullt. Hållet är i hela krediter, minst en, så varje begäran behöver minst 10 satsar gratis på standardbalansen eller 100 satsar på Pro för att starta. Endast den faktiska kostnaden debiteras; resten släpps när den slutar. En lång begäran håller sitt håll så länge den körs; om de hållna krediterna slutar vara tillgängliga ändå, stannar en ström med en 402 insufficient_balance Om den faktiska kostnaden är mer än saldot kan betala, tas hela saldot, resten är skyldig (owed_sats I den nymbot objekt, och en negativ balansräkning). Vad som är skyldigt betalas först ut ur de nästa krediter som når den balansräkningen.Tills det betalas kan inget på den balansräkningen spenderas: inte av API, svar i appen, en överföring eller en gåva.
• Inte tillräckligt med kredit. Om saldot inte kan täcka innehavet avslås begäran med 402 Felet säger vilken balans är kort, hur många satser begäran behöver och hur många är gratis. max_tokens Det innebär mindre hållning.
• och misslyckanden. En förfrågan som misslyckas kostar ingenting, såvida inte leverantören fakturerade för det arbete som den gjorde innan misslyckades, eller en webbsökning eller nymbot/auto En ström du klipper av debiteras för de tokens som leverantören rapporterar: Nymbot fortsätter att läsa leverantörens ström i upp till 25 sekunder efter att du lämnar för att få det antalet.
• Webbsökning kostar $ 0,008 en sökning, omvandlas till sats, varje gång en sökning körs, oavsett om modellen sedan svarar eller misslyckas.

Varje svar säger vad det kostar. JSON-svar bär en nymbot objekt med saldot från vilket det betalades, avgiften i krediter och satser, och vad som återstår:

Kostnadsobjektet

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

Betalda svar bär också dessa rubriker, vilket är där du ska leta efter kostnaden för ett svar som inte är JSON, till exempel tal:

Räntor per miljon tokens, redan inklusive avgiften och marginalen, är i Modelllista i dollar och sats, och på Prislistan ärOm Bitcoin-priset inte kan läsas, returnerar betalda förfrågningar 503 price_unavailable med Retry-After: 60 Istället för att gissa.

misstag

Varje fel har samma form, en som OpenAI-klienterna redan förstår. code är ett stabilt namn som du kan matcha med; message Det är för människor och kan förändras.

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

Två undantag är:

• /api/v1/messages svar i Anthropics felformat, eftersom det är vad Anthropic-klienter analyserar: {"type": "error", "error": {"type": "authentication_error", "message": "…"}}Typen följer 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 strömningsförfrågan som misslyckas innan dess första byte får ett vanligt JSON-fel med statusen ovan, inte en händelseström.

Felmeddelanden innehåller aldrig en annan tjänsts interna detaljer.En leverantörs eget fel ordnas om innan det når dig.

gränser

En länk till en bild måste peka på en offentlig värd: en adress på ett privat eller lokalt nätverk, eller på Nymbots egna webbplatser, nekas. leverantörspasning som gäller i appen gäller här också, så ett utbrott av förfrågningar till en leverantör kan sakta ner snarare än misslyckas.

Vad elden kan se

API: n är inte privat på det sätt apparna är, och det är värt att vara exakt om hur.

• Den är inte end-to-end krypterad. I apparna förseglas ett meddelande på din enhet till nycklar som bara Nymbot håller och reser som en Gåva WrapEn API-begäran är vanlig HTTPS: den är krypterad på vägen till Nymbot, och Nymbots server läser den i det klara för att hantera den.
• Prompts och svar sparas inte. Vad som hålls är räkningen: för varje begäran tid, modell, typ, token räknas, kostnad, balans, nyckel och om det lyckades, i 90 dagar, vilket är vad Söker historia En användarlogg för samma begäran (tid, typ, modell, tokenräkning, kostnad, varaktighet och om den använde webbsökning eller lyckades) bevaras också i 90 dagar, tillsammans med appens egen.
• Allt annat som hålls för en nym är litet och listat här. Brandnycklar lagras som en hash, aldrig nyckeln, med deras namn, en kort hint, utgiftskapacitet, återställningsperiod, utgång och när de gjordes och senast användes; endast de senaste 50 återkallade nycklarna behålls. Automatiska toppar Portföljanslutningen lagras krypterad, med dess tröskel, belopp och resultatet av den senaste uppgraderingen. Videojobb hålls i 24 timmar. Förfrågningar som betalas per samtal lämnar endast en Lightning-betalningshash i 7 dagar och en hashad återbetalningstoken i 30 dagar, kopplad till ingen nym. Avgifter som en balans inte kunde täcka hålls som skyldiga tills en uppgraderare betalar dem.
• Att radera appen tar bort den. A Utrustning Wipe återkallar och raderar varje API-nyckel, och raderar frågehistorik, användarloggar, plånbokanslutning och videojobb.
• Modellens leverantör ser din begäranKatalogmodeller körs på sina tillverkare; standardvägar och inbäddningar körs på Cloudflare.
• Genererade medier är offentliga. Bilder och videor som levereras som länkar laddas upp till offentliga Blossom-filvärdar, där filens adress är dess hash.Vem som helst med länken kan öppna den, och Nymbot kan inte hämta den igen. b64_json och en genererad bild återkommer i svaret och laddas aldrig upp.
• Så är bilderna du ger en generator. En bild du laddar upp till Edit, eller skicka som a data: URL i en generator image_url, laddas upp till en offentlig Blossom värd först så att generatorn kan hämta den, och detsamma gäller för den. https:// Bilder i en chattförfrågan går till modellens leverantör, inte till Blossom.
• En nyckel är kopplad till din nym. Allt en nyckel spenderar kommer från din nym-balans, så API-användning är inte AnonymaOm du vill att API-användningen ska hållas åtskilt från din vardagliga nym, gör nycklarna från en separat nym med sin egen balans.

Om du behöver skydd av apparna, använd apparna. API:n är för när du behöver modellerna i dina egna verktyg.

Varje slutpunkt

“Nym” betyder en begäran signerad av din Nostr-nyckel, som beskrivs i Signera konto förfrågningarFör verktyg som redan talar dessa format, se Verktyg och SDK, och för kodningsagenter som Claude Code, Codex och Cline, se Kodningsverktyg.