Base di cunniscenza / Sviluppatori

Rivista di l'API

I mudelli, i generatori è u bilanciu chì u utilizate in l'app, da u vostru propiu codici. L'API parla i furmati OpenAI è Anthropic, cusì a maiur parte di i strumenti è SDK funzionanu cambiendu un URL di base è una chìave.

Questa pagina hè tradutta in macchina per comodità. L'uriginale in inglese hè a versione chì si applica.

Chì hè l'API

Un API HTTP su nymbot.ai chì risponde à e stese dumande chì un client OpenAI o Anthropic manda digià. Vuccu:

• Completazioni di Chat, u API di risposte è Messaggi di Anthropic, cù u streaming, i strumenti, e i ritrattu, u ragionamentu è a ricerca web, per ogni mudellu in u catalogu è per l'auto-rutamente di Nymbot stessu.
• Immagini, video, discursu, trascrizione è inserimenti.
• U vostru bilanciu, Ricariche Lightning, ricariche automatiche da u vostru portafoglio è un u storia di ciò chì ogni dumanda costa.

Hè pagatu da i stessi dui bilanci cum l'app, à istessi prezzi. ùn ci hè micca un abbonamentu è micca una quotà gratuita nantu à l'API: ogni richiesta hè pagata cù i crediti chì avete accattatu.

Quello chì l'API ùn fà micca hè aghjunghje nente di propi à Nymbot. I vostri messaggi andanu à u mudellu cum'è mandati da voi: micca un prompt di sistema di Nymbot, micca memoria, micca data o indizi di lingua. Quello chì torna hè a risposta di u mudellu è una nota di ciò chì hà costatu.

URL di base

Ogni endpoint si trova sottu à /api/v1/Un caminu sconosciutu torna 404 è un percorsu cunnosciu chjamatu cù u metodu sbagliatu torna 405, tutti dui in JSON.

L'API risponde à e richieste cross-origin da quìsiunque situ, cusì una pagina di u browser pò chjamallu. Tuttu ciò chì vi mandate à un browser pò esse lettu da quiconte apre itlu, però, dunque fate solu quella cù una chìave chì hà un piccolu cap. I terminali firmati cù u vostru nym (le chjavi, u riassuntu di u contu, l'auto-ricarica NWC è u rimboursamentu) sò l'eccezione: in un navigatore rispondenu solu à i siti propi di Nymbot. Vedi firmatura di dumande di contu.

Mandate ogni corpu JSON cù Content-Type: application/jsonCualche altru tipu hè rigettatu cù 415, dunque un formulariu HTML simplice o un text/plain una dumanda da un altru situ ùn pò micca reach l'API. Cum'è cURL, passaghjula -H "Content-Type: application/json" accumpagnatu da -d.

Chiavi API

E chjavi sò fatte in l'app. Aprili API in a barra laterale di l'app web, o in u menù su Android è iOS, è toccate Crea a chìave. Dàghia un nome è, si vi piace, un limite è una data di scadenza.

A chìave hè mostra una volta sola. Copiatella in un postu sicuru prima di chiudè a foglia: Nymbot tene solu una imprunta di essa, cusì ùn pò micca mostrale di novu. Una chìave persa ùn pò micca esse ricuperata; revocatevi a è fate n'antra.

Una chìave pare$$\dots$$ sk-nymbot- seguivu da 43 lettere, cifre, tiretti è sottilinei. L'app lista ogni chiave per u so nome è un breve suggerimentu cum'è sk-nymbot-Qm7x…c2Lw.

• Una chiave appartene à u to nym. Ellu spende u vostu saldu, è solu u vostu nym pò fà, cambià o revocàlu. Chiacchìsia tene a chìave pò spende cù ela, perciò trattatelu cum'è una parolla d'ordine.
• I caps sò in sats. Una chìave pò avè un capu di spesa, è u capu pò resettauà ogni ghjornu, ogni settimana (lunedì) o ogni mese (u primu), à 00:00 UTC. Ellu conta i dui saldi, un creditu standard cum'è 10 sats è un creditu Pro cum'è 100, dunque significa a stissa cosa indipendentemente da quale saldu spende una dumanda. Prima chì una dumanda si eseghe, u massimu chì puderia custà (arrotondatu à crediti interi) hè settu contru à ciò chì resta di u capu. S'ellu ùn si ferma micca, a dumanda hè rifiutata cù 403 key_limit_reached, ancu si a risposta si fora stata sottu à u limitu; l'erroru dice quanta ne resta è quandu u limitu si resetta. Abassendu max_tokens riduce quellu casu più peggioru. Una dumanda hè fatturata versu u so veru costu è quella si cunta contru u limite, dunque si u fornitore raporta più token di quelli chì sò stati messi da parte, l'ultima dumanda chì si adatta pò purtà a chìave un pocu oltre u so limite; a successiva hè dopu rifiutata.
• Un cappu espartu ferma solu a spesa. Una chìave à u so capu pò ancu verificà u bilanciu, legge a so storia, listà i mudelli, cuntà i token, ricaricà è verificà un video chì ha digià cuminciatu.
• A scadenza hè opzionale. Dopu a data chì avete stabilitu, a chìe ferma di funziona.
• A revoca hè immediata è definitiva. Una chiave revocata fallisce a so prossima dumanda. Ella resta in a lista, marcata cum'annullata, perchè a so storia di spesa hà ancu sensu.
• Pudete avè至 un massimu di 25 chjavi attive, ognuna cù u so propiu nomu. Cambià u periodu di reset di una chjave cumincia un novu periodu da zero.

A stissa foglia mostra a spesa di ogni chiave in stu periodu è in tuttu u cumulatu, quandu hè stata usata ultimamente, i dui vostri saldi, è e vostre richieste API recente. I termini di cunnessione dunaì sottu sò documentati sottu à gestione di e chjavi.

Autenticazione di una dumanda

Mandate a chìave in unu di sti headers. Sò equivalenti, quindi utilizate quella chì u vostru client ferma per difettu:

Una chìave mancante, ignota, revucata o scaduta restituisce 401, cù u codici missing_api_key, invalid_api_key, revoked_api_key o expired_api_keyA l'elencà di i mudelli, i mudelli audiuli è e voci, è i metudi di pagamentu ùn hè necessariu micca chì una chìave.

Immagini, video, voce, trascrizione è embeddings ponu esse pagati ancu una richiesta à vota via Lightning senza alcuna chìave: mandate a richiesta senza una è pagate a fattura in u 402 risposta. Vedi paghje per dumanda senza una chiave.

A gestione di e chjavi, u riassuntu di u cuntu è i ricarichi automatici sò l'eccezzione: essi pighentu una firma da u vostru nym invece di una chjave, dunque una chjave fuggiuta ùn pò micca fà altre chjavi. Vedi firmatura di dumande di contu.

A vostra prima dumanda

Mette a chiave in una variabile d'ambiente, poi dumandà qualcosa à un mudellu. L'esempiamenti in tutta queste pagine a lighe da 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 hè u propi routage di Nymbot, pagatu da u saldu standard. Pone invece un ID di un mudellu di u catalogu, cum'è anthropic/claude-sonnet-5, per utilizà quellu mudellu da u bilanciu Pro. Lista di i modelli dà ogni id.

Quanto costa una dumanda

L'API fattura esattamente cum'è fà a app.

• Quale bilanciu. nymbot/auto spende u standard bilanciu (10 sats à u creditu). Ogni altru modu di chat spende u Pro bilanciu (100 sats à creditu). U generatore d'imaghjìni standard è a voce standard spennenu crediti standard; ogni altru generatore spenne Pro. I modelli di l'embedding spennenu crediti standard. A trascrizione spenne crediti standard quandu u bilanciu standard pò cunvènu, è crediti Pro altri casu. A lista di i mudelli dice quale bilanciu spenne ogni mudellu.
• Quanto. Una dumanda di chat hè misurata in funzione di i token chì u mudellu hà veramente lettu è scrittu, à i tariffi pubblicati da u furnituri. Quellu prezzu hà una tassa di 5% chì hè aghjunta è poi moltiplicatu per 1.5, dunque paghe 1.575 volte u prezzu di lista di u furnituri. Hè cunvertitu in sats à u prezzu in tempo reale di u Bitcoin è fatturatu in millesimi di un creditu. E ritratti prufessiunali, u video è u discorsu sò prunziati per generazione, per seconde o per caratteri, è a trascrizzione per seconde di audio, cù a stessa tassa è u stessa margine. A ritrattu standard hè un prezzu fissu di 5 crediti standard è a voce standard un prezzu fissu di 3.
• U minimu. Ogni dumanda misurata chì si eseghice costa almeno 0.05 creditu: metà un sat nantu à u saldu standard, 5 sats nantu à u Pro. I franchi di un creditu sò riportati, non arrotondati ogni volta.
• Attende, poi stazzatevi. Prima chì una richiesta venga eseguta, u massimu chì puderia custà hè ritagliatu da u vostre saldu, basatu nantu à ciò chì avete mandatu è u massimu di token chì puderia scrive. U testu fora di l'ASCII semplice hè misuratu in basa à i so byte UTF-8, è i digiti è a punteggiatura ASCII contanu cum'è un token ciasununa, cusì u testu in qualsiasi scrittura, u codice è i 숫ri sò ritagliati in tuttu u so largu. U ritagliu hè in crediti interi, 至 u menu unu, cusì qualsiasi richiesta hà bisognu di 至 u menu 10 sats liberi in u saldu standard o 100 sats in Pro per cumencia. Sò u costu attuale chì hè addebitatu; u restu hè liberatu ultimamente chì u prucessu finisce. Una richiesta lunga mantiene u so ritagliu per tutta a durata chì ella corre; s'ellu i crediti ritagliati scupanu di esse dispunibili comunque, un stream si ferma cù un 402 insufficient_balance un eventu d'erroru, è ciò chì hè statu generatu hè fatturatu. S'u coste reale hè più ch'u saldu pò pavà, tuttu u saldu hè pigliatu, u restu hè debitu (owed_sats in u nymbot oggettu, è un saldu negativu). Ciò chì hè debutu hè pagatu prima cù i prossimi crediti chì arrivanu à quellu saldu. Finché ùn hè pagatu, nente di quellu saldu pò esse spesi: né da l'API, nè da e risposte in l'app, nè da un trasferimentu o da un regalu.
• Troppu pochi creditu. Si u saldu ùn pò micca cunvè chì u bloccu, a dumanda hè rifiutata cù 402 prima chì quìede quìcosa. L'errora dice chì saldu hè curtu, quantu sats a dumanda hà bisognu è quantu sò liberu. Unu più piccolu max_tokens vòle dì un più piccolu mantinimentu.
• Fallimenti. Una dumanda chì fallisce ùn costa nenti, fora si u fornitore fattura per u travagliu chì hà fattu prima di fallisce, o una ricerca web o u nymbot/auto task verificà s'era digià executatu; dopu à đó hè ciò chì paghe 您, almenu 0.05 creditu. Un stream chì avete tagliatu hè fatturatu per i token chì u fornitore raporta: Nymbot continua à legge u stream di u fornitore per 至 25 sicondi dopu à u vostre uscita per piglià quellu conteggiu. S'ellu ùn arriva micca, u fatturatu hè stimatu da ciò chì avete mandatu è ciò chì hè statu scrittu, è per un mudellu chì ragiona include tutta a permessione di output di a ritenzione. Una richiesta chì a so cunnessione cade finisce comunque è hè fatturata.
• Ricerca web custu $0.008 per ricerca, cunvertitu in sats, ogni volta chì una ricerca si ferma, sia chì u mudellu risponde sia chì fallisce. I pagine chì legge sò ancasu mandate à u mudellu cum'è input, dunque aghjunghjun u so numeru di token.

Ogni risposta dice ciò chì si cuntenutu. E risposte JSON portanu un nymbot oggettu cù u saldu da u quale hè statu pagatu, a carica in crediti è sats, è ciò chì resta:

L'oggettu di u coste

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

I rispuste paghate portanu ancu sti intestazioni, chì hè u locu induve cercà u coste di una rispusta chi ùn hè micca JSON, cum'è u parlu:

E tariffe per milione di token, già inclusive di a commissione è di u margine, sò in u lista di i mudelli in dollari è in sats, è in continuu a scheda di i prezzi. S'u prezzu di u Bitcoin ùn pò micca esse lettu, i richesti pagati ritornanu 503 price_unavailable cu u Retry-After: 60 pi invece di indovinà.

Errori

Ogni errore hà a stissa forma, quella chì i clienti di OpenAI capiscean anu già. code è un nome stabile indu pudete fà a corrispondenza; message è per i populi è pò cambià.

Corpu di l'erroru

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

Dui eccezioni:

• /api/v1/messages risposte in u formatu d'error di Anthropic, perchè hè chistu chì i clienti di Anthropic interpretanu: {"type": "error", "error": {"type": "authentication_error", "message": "…"}}U tipu segu u statutu: invalid_request_error, authentication_error, billing_error (402), permission_error, not_found_error, request_too_large, rate_limit_error, api_error o overloaded_error (503).
• Una richiesta di streaming chì fallisce prima chì u so primu byte riceve un errore JSON ordinariu cù u statu sopra citatu, micca un stream d'eventi. Un fallimentu dopu chì u stream hà cuminciatu hè mandatu cum'è l'ultimu eventi di u stream, in u formatu propiu di quellu endpoint.

I messaggi d'erroru ùn cuntenenu mai i dettagli internu di un altru serviziu. L'erroru propiu di un fornitore hè rimodulatu prima chì arrivi à voi.

Limiti

Un ligame vers una imaghjina deve puntà vers u situ di un ospite pulbicu: un indirizzu in un rete privata o locale, o annantu à i siti propi di Nymbot, hè rifiutatu. U regulamentu di u fornitore chì si applica in l'app si applica ancu quì, cusì una serie di richieste à un fornitore pò esse rallentata invece di fallisce.

Cosa pò vede l'API

L'API ùn hè micca privata cum'è l'applicazioni, è hè worth esse esattu nantu à u modu.

• Ùn hè micca criptatu da punta à punta. In i applis, un messaghju hè sigillatu nantu u vostru dispositivu per e chjavi chì solu Nymbot detiene è viaghja cum'è un impacchettamentu di regaluUna richiesta API hè un HTTPS ordinariu: hè criptata in u caminu versu Nymbot, è u servitore di Nymbot a legge in chiaro per gestisce ela.
• I prompti è e risposte ùn sò micca stivati. Passanu per u mudellu è a storia di e ricerca vi mostra. Un registru d'usu d'a stessa dumanda (tempu, tipu, mudellu, conteggiu di token, coste, durata è s'ellu hà usatu a ricerca web o s'ellu hè riuscitu) hè ancu conservatu per 90 ghjorni, accantu à u propiu di l'app.
• Tuttu u restu tenutu per un nym hè picculu è registratu quì. Chiavi API sò stivati cum'è un hash, mai a chìave, cù u so nome, un breve indizi, u limite di spesa, u periodu di reset, a scadenza è quandu sò stati creati è ultimu utilizati; solu e 50 chìavi revocate più recente sò conservate. An ricarica automatica a cunnessione di u wallet hè sturata criptata, cù a so soglia, u miktu è u risultatu di l'ultimu ricaricamentu. I travagli video sò custuriti per 24 ore. E dumande pagate per chjamata lascianu solu un hash di pagamentu Lightning per 7 ghjorni è un tòken di rimpursu hashatu per 30 ghjorni, ligatu à nisun nìm. E carichi chì un saldu ùn puderia micca custatà sò custuriti cum'è debuti finchè un ricaricamentu ùn i paga.
• S'ell'app sicura si cancella. A effacement di u dispozitivu revoca è elimina ogni chìave API, è elimina a storia di e dumande, i registri d'usuage, a cunnessione di u wallet è i travagli video. U saldu è qualsiasi debitu rimanghenu nantu à u nym.
• U pruviditore di u mudellu vede a vostra dumanda, cum'è da l'app. Catalughe i mudelli runnan chez i so üretori; i rutti standardi è i embeddings runnan nantu à Cloudflare.
• I media generati sò publici. E immagini è i video mandati cum'è ligami sò caricati nantu à l'host Blossom pubblici, induve l'indirizzu di un filu hè u so hash. Chiascunù cù u ligame pò aprelu, è Nymbot ùn pò micca rimuovelu di novellu. Chiedete per b64_json è una imaghjina generata chì ritorna in a rispusta è ùn hè mai caricata.
• Dunque, e imaghjini ca dê u dai sò un generatore? Una foto chì vulgi caricà in modifica, o mandate com u data: URL in un generatore image_url, hè caricatu nantu à un ospite Blossom public prima trà perì chì u generatore possa ritirallu, è a stissa cosa si applica à ellu. Una ritrattu mandatu da https:// U ligame hè passatu cum'è u ligame đó. I ritrattu in una dumanda di chat vanno à u fornitore di u mudellu, non à Blossom.
• Una chiave hè ligata à u vostru nym. Tutte e cose chì una chiave spende si pigghianu da u saldu di u vostru nym, dunque l'usu di l'API ùn hè micca anonimu. S'ellu vulete usà l'API tenuta separata da u vostru nym di ogni ghjornu, fate e chjavi da un nym separatu cù u so propiu balanze.

S'avete bisognu di a protezzione di l'applicazioni, utilizate l'applicazioni. L'API hè per quandu avete bisognu di i mudelli in i vostri strumenti.

Ogni endpoint

“Nym” vole dì una dumanda firmatu da a vostra chìave Nostr, descritta in firmatura di dumande di contu. Per i strumenti chì parlanu digià questi furmati, vede strumenti è SDK, è per i agenti di codifica cum'è Claude Code, Codex è Cline, vede strumenti di programmazione.