Basis pengetahuan / pengembang

Pandangan api

Model, generator dan keseimbangan yang Anda gunakan dalam aplikasi, dari kode Anda sendiri. API berbicara format OpenAI dan Anthropic, sehingga sebagian besar alat dan SDK bekerja dengan mengubah URL dasar dan kunci.

Halaman ini diterjemahkan dengan mesin untuk kenyamanan. Versi asli bahasa Inggris adalah versi yang berlaku.

Apa itu api

Menggunakan HTTP API nymbot.ai yang menjawab permintaan yang sama yang sudah dikirimkan oleh klien OpenAI atau Anthropic.

• Chatting yang lengkap, yang Jawaban API Dan Pesan antropologis, dengan streaming, alat, gambar, argumen dan pencarian web, untuk setiap model di Catatan dan untuk auto-routing Nymbot sendiri.
• gambar, Video yang, pidato, transkripsi Dan embeddings.
• Milikmu keseimbangan, Pengembangan Lightning Top-ups, Top-up otomatis dari dompet Anda dan a Sejarah berapa biaya setiap permintaan.

Dibayar dari dua jenis yang sama Keseimbangan Tidak ada langganan dan tidak ada kuota gratis pada API: setiap permintaan dibayar dari kredit yang Anda beli.

Apa yang tidak dilakukan API adalah menambahkan apa pun dari Nymbot sendiri. pesan Anda pergi ke model saat Anda mengirimkannya: tidak ada petunjuk sistem Nymbot, tidak ada memori, tidak ada petunjuk tanggal atau bahasa.

url dasar

Setiap akhir hidup di bawah /api/v1/Jalan yang tidak diketahui kembali 404 dan jalan yang dikenal yang disebut dengan metode yang salah kembali 405Begitu juga dengan JSON.

Apapun yang Anda kirim ke browser dapat dibaca oleh siapa saja yang membukanya, jadi hanya melakukannya dengan kunci yang memiliki kunci kecil. KepalaEndpoint yang ditandatangani dengan nym Anda (keys, ringkasan akun, NWC auto-top-up dan pengembalian uang kembali) adalah pengecualian: dalam browser mereka hanya menjawab situs Nymbot sendiri. Menandatangani permintaan akun.

Mengirimkan setiap tubuh JSON dengan Content-Type: application/jsonSetiap jenis lainnya ditolak dengan 415, maka bentuk HTML sederhana atau text/plain permintaan dari situs lain tidak dapat mencapai API. dengan cURL, -H "Content-Type: application/json" Bersama dengan -d.

Kunci api

Kunci dibuat dalam aplikasi. terbuka api yang di sidebar aplikasi web, atau di menu di Android dan iOS, dan ketuk Membuat KunciBerikan nama dan, jika Anda mau, cap dan tanggal kedaluwarsa.

Kunci ditampilkan sekali. salin ke tempat yang aman sebelum Anda menutup lembar: Nymbot hanya menyimpan sidik jari dari itu, sehingga tidak dapat menunjukkannya kepada Anda lagi. Kunci yang hilang tidak dapat dipulihkan; batalkan dan buat yang lain.

Kunci yang terlihat seperti sk-nymbot- diikuti oleh 43 huruf, digit, dash dan sub-score. aplikasi mendaftar setiap kunci dengan namanya dan petunjuk singkat seperti sk-nymbot-Qm7x…c2Lw.

• Kunci adalah milik nym Anda. Ini menghabiskan saldo Anda, dan hanya nym Anda yang dapat membuat, mengubah atau membatalkannya. siapa pun yang memegang kunci dapat menghabiskan dengan itu, jadi perlakukan seperti kata sandi.
• Caps adalah dalam sats. Kunci dapat memiliki batas pengeluaran, dan batas dapat dipulihkan setiap hari, setiap minggu (Monday) atau setiap bulan (yang pertama), pada 00:00 UTC. Ini menghitung keduanya saldo, satu kredit standar sebagai 10 sats dan satu kredit Pro sebagai 100, jadi itu berarti sama apapun saldo permintaan menghabiskan. 403 key_limit_reached, bahkan jika jawaban akan datang di bawah cap; kesalahan mengatakan berapa banyak yang tersisa dan kapan cap reset. max_tokens Sebuah permintaan dikenakan biaya apa yang sebenarnya harganya dan yang dihitung terhadap cap, jadi jika penyedia melaporkan lebih banyak token daripada yang ditinggalkan, permintaan terakhir yang cocok dapat mengambil kunci sedikit melampaui capnya; yang berikutnya kemudian ditolak.
• Pengeluaran yang dihabiskan hanya menghentikan pengeluaran. Kunci pada capnya masih dapat memeriksa saldo, membaca sejarahnya, daftar model, menghitung token, memonitor dan memeriksa video yang sudah dimulai.
• Expiry adalah opsional. Setelah tanggal yang Anda tetapkan, kunci berhenti bekerja.
• Penghapusan adalah segera dan akhir. Kunci yang dibatalkan gagal permintaan berikutnya. tetap dalam daftar, ditandai dibatalkan, sehingga riwayat pengeluaran masih masuk akal.
• Anda dapat memiliki hingga 25 kunci aktif, masing-masing dengan nama sendiri. mengubah periode reset kunci memulai periode baru dari nol.

lembar yang sama menunjukkan pengeluaran setiap kunci selama periode ini dan secara total, ketika terakhir digunakan, kedua saldo Anda, dan permintaan API Anda baru-baru ini. Manajemen Kunci.

Mengautentikasi permintaan

Kirimkan kunci di salah satu header ini. mereka setara, jadi gunakan apa pun yang klien Anda kirim secara default:

Kunci yang hilang, tidak diketahui, dibatalkan atau habis dikembalikan 401Dengan kode tersebut missing_api_key, invalid_api_key, revoked_api_key atau expired_api_keyDaftar model, model audio dan suara, dan metode pembayaran tidak membutuhkan kunci.

Gambar, video, suara, transkrip dan embeddings juga dapat dibayar untuk satu permintaan sekaligus di Lightning tanpa kunci sama sekali: kirim permintaan tanpa satu dan membayar tagihan di 402 Jawaban : lihat Pembayaran per permintaan tanpa kunci.

Manajemen kunci, ringkasan akun dan top-up otomatis adalah pengecualian: mereka mengambil tanda tangan dari nym Anda alih-alih kunci, sehingga kunci yang bocor tidak dapat membuat lebih banyak kunci. Menandatangani permintaan akun.

Permintaan pertama Anda

Letakkan kunci dalam variabel lingkungan, kemudian tanyakan pada model sesuatu. 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 adalah routing Nymbot sendiri, dibayar dari saldo standar. letakkan id model katalog di sana, seperti anthropic/claude-sonnet-5, untuk menggunakan model tersebut dari Pro Balance. Daftar Model Memberikan setiap ID.

Berapa biaya permohonan

API menghitung persis seperti yang dilakukan aplikasi.

• Keseimbangan yang nymbot/auto Menghabiskan Standar keseimbangan (10 sats a credit). setiap model chat lainnya menghabiskan Untuk saldo (100 sats satu kredit). Generator gambar standar dan suara standar menghabiskan kredit standar; setiap generator lainnya menghabiskan Pro. Embeddings menghabiskan kredit standar. Transcription menghabiskan kredit standar ketika saldo standar dapat menutupi itu, dan kredit Pro sebaliknya. Daftar model mengatakan saldo mana yang dihabiskan setiap model.
• Berapa banyak Sebuah permintaan obrolan diukur pada token yang sebenarnya dibaca dan ditulis oleh model, pada tarif yang diterbitkan oleh penyedia. Harga tersebut memiliki biaya 5% ditambahkan dan kemudian dibantah dengan 1,5, sehingga Anda membayar 1.575 kali harga daftar penyedia. Ini diubah menjadi taruhan pada harga Bitcoin langsung dan dibayarkan dalam seribu dari kredit. Pro gambar, video dan suara dibayar per generasi, per detik atau per karakter, dan transkrip per detik audio, dengan biaya dan margin yang sama. Gambar standar adalah flat 5 kredit standar dan suara standar flat 3.
• yang minimal Setiap permintaan yang diukur yang berjalan biaya setidaknya 0.05 kredit: setengah duduk pada saldo standar, 5 sats pada Pro.
• Tahan dan kemudian menetap. Sebelum permintaan berjalan, biaya yang paling mungkin ditahan dari saldo Anda, berdasarkan apa yang Anda kirimkan dan jumlah token yang mungkin ditulisnya. Teks di luar ASCII biasa berukuran dari byte UTF-8, dan angka-angka ASCII dan titik-titik dihitung sebagai token masing-masing, sehingga teks dalam setiap script, kode, dan nomor ditahan secara penuh. Hold adalah dalam seluruh kredit, setidaknya satu, sehingga setiap permintaan membutuhkan setidaknya 10 sats gratis pada saldo standar atau 100 sats pada Pro untuk memulai. Hanya biaya sebenarnya yang dikenakan biaya; sisanya dilepaskan ketika selesai. Sebuah permintaan panjang mempertahankan holdnya selama berjalan; jika kredit yang ditahan berhenti tersedia, aliran berhenti dengan 402 insufficient_balance Jika hasilnya lebih besar dari hasil yang diperoleh, maka hasilnya lebih besar dari hasil yang diperoleh, maka hasilnya lebih besar (owed_sats Di dalam nymbot Objek, dan saldo negatif). Apa yang harus dibayar pertama dari kredit berikutnya yang mencapai saldo itu. Sampai dibayar, tidak ada yang dapat dihabiskan pada saldo itu: tidak oleh API, jawaban dalam aplikasi, transfer atau hadiah.
• Tidak cukup kredit. Jika saldo tidak dapat menutupi kepemilikan, permintaan ditolak dengan 402 sebelum sesuatu berjalan. kesalahan mengatakan saldo mana yang pendek, berapa banyak sats permintaan dibutuhkan dan berapa banyak yang gratis. max_tokens Ini berarti lebih sedikit tahan.
• Kegagalan yang Permintaan yang gagal tidak biaya apa-apa, kecuali penyedia menghitung untuk pekerjaan yang dilakukan sebelum gagal, atau pencarian web atau nymbot/auto Task check sudah berjalan; maka itulah yang Anda bayar, setidaknya 0.05 kredit. Sebuah aliran yang Anda potong dikenakan biaya untuk token yang dilaporkan oleh penyedia: Nymbot terus membaca aliran penyedia hingga 25 detik setelah Anda meninggalkan untuk mendapatkan hitungan itu.
• pencarian web biaya $0.008 satu pencarian, dikonversi menjadi sats, setiap kali pencarian berjalan, apakah model kemudian menjawab atau gagal. halaman yang dibaca juga dikirim ke model sebagai input, sehingga mereka menambahkan token mereka.

Setiap jawaban mengatakan berapa biaya. jawaban JSON membawa nymbot objek dengan saldo yang dibayar dari, biaya dalam kredit dan sats, dan apa yang tersisa:

Biaya objek

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

Tanggapan berbayar juga membawa header ini, di mana untuk mencari biaya jawaban yang tidak JSON, seperti pidato:

Biaya per juta token, sudah termasuk biaya dan margin, berada di Daftar Model Dalam dolar dan sats, dan pada Daftar HargaJika harga Bitcoin tidak dapat dibaca, permintaan yang dibayar akan dikembalikan 503 price_unavailable dengan Retry-After: 60 Daripada hanya menebak.

Kesalahan

Setiap kesalahan memiliki bentuk yang sama, yang klien OpenAI sudah mengerti. code adalah nama yang stabil yang dapat Anda pasang; message untuk orang lain dan dapat berubah.

Kesalahan tubuh

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

Ada dua pengecualian:

• /api/v1/messages jawaban dalam format kesalahan Anthropic, karena itulah yang dipelajari oleh klien Anthropic: {"type": "error", "error": {"type": "authentication_error", "message": "…"}}Jenis ini mengikuti status: invalid_request_error, authentication_error, billing_error (402), permission_error, not_found_error, request_too_large, rate_limit_error, api_error atau overloaded_error (503).
• Permintaan streaming yang gagal sebelum bajet pertamanya mendapatkan kesalahan JSON biasa dengan status di atas, bukan aliran acara.

Pesan kesalahan tidak pernah berisi rincian internal layanan lain. kesalahan penyedia sendiri diubah kata sebelum mencapai Anda.

Batas

Link ke gambar harus menunjuk ke host publik: alamat di jaringan pribadi atau lokal, atau di situs Nymbot sendiri, ditolak. pacing penyedia yang berlaku di aplikasi juga berlaku di sini, sehingga ledakan permintaan ke satu penyedia dapat diperlambat daripada gagal.

Apa yang dapat dilihat oleh api

API tidak pribadi dalam cara aplikasi, dan itu layak untuk tepat tentang bagaimana.

• Itu tidak end-to-end dienkripsi. Dalam aplikasi, pesan ditutup pada perangkat Anda untuk kunci hanya Nymbot memegang dan bepergian sebagai Penghargaan WrapPermintaan API adalah HTTPS biasa: itu dienkripsi di jalan ke Nymbot, dan server Nymbot membacanya dengan jelas untuk menangani.
• Pertanyaan dan jawaban tidak disimpan. Apa yang disimpan adalah tagihan: untuk setiap permintaan waktu, model, jenis, token hitung, biaya, saldo, kunci dan apakah itu berhasil, selama 90 hari, yang Menginginkan Sejarah Catatan penggunaan permintaan yang sama (waktu, jenis, model, jumlah token, biaya, durasi dan apakah itu menggunakan pencarian web atau berhasil) juga disimpan selama 90 hari, bersama dengan aplikasi sendiri.
• Semua yang lain yang dipegang untuk nym kecil dan tercantum di sini. Kunci api disimpan sebagai hash, tidak pernah kunci, dengan nama mereka, petunjuk singkat, pengeluaran cap, periode reset, kedaluwarsa dan ketika mereka dibuat dan terakhir digunakan; hanya 50 kunci yang paling baru dibatalkan disimpan. Top-up otomatis Hubungan dompet disimpan dienkripsi, dengan ambang batasnya, jumlahnya, dan hasil top-up terakhir. pekerjaan video disimpan selama 24 jam. permintaan yang dibayarkan per panggilan hanya meninggalkan hash pembayaran Lightning selama 7 hari dan token pengembalian dana hash selama 30 hari, terhubung dengan tidak ada nym. Biaya yang tidak dapat ditutupi saldo tetap sebagai berutang sampai top-up membayarnya.
• Menghapus aplikasi akan menghapusnya. A Perangkat Wipe membatalkan dan menghapus setiap kunci API, dan menghapus riwayat kueri, catatan penggunaan, koneksi dompet dan pekerjaan video.
• Penyedia model melihat permintaan AndaModel katalog berjalan pada pembuatnya; rute standar dan embeddings berjalan pada Cloudflare.
• Media yang dihasilkan adalah publik. Gambar dan video yang dikirim sebagai tautan diunggah ke host file Blossom publik, di mana alamat file adalah hashnya.Siapa pun dengan tautan dapat membukanya, dan Nymbot tidak dapat mengunduhnya lagi. b64_json dan gambar yang dihasilkan kembali dalam tanggapan dan tidak pernah diunggah.
• Begitu juga dengan gambar-gambar yang Anda berikan pada generator. Gambar yang Anda upload ke Edit yang, atau mengirimkan sebagai a data: URL pada generator image_url, diunggah ke host Blossom publik terlebih dahulu sehingga generator dapat mengambilnya, dan hal yang sama berlaku untuk itu. https:// Gambar dalam permintaan obrolan pergi ke penyedia model, bukan ke Blossom.
• Kunci yang terhubung dengan nym Anda. Semua yang dihabiskan kunci berasal dari saldo nym Anda, jadi penggunaan API tidak anonimnyaJika Anda ingin penggunaan API tetap terpisah dari nym sehari-hari Anda, buat kunci dari nym terpisah dengan keseimbangan sendiri.

Jika Anda membutuhkan perlindungan aplikasi, gunakan aplikasi. API adalah untuk saat Anda membutuhkan model dalam alat Anda sendiri.

Setiap Endpoint

“Nym” berarti permintaan yang ditandatangani oleh kunci Nostr Anda, yang dijelaskan di Menandatangani permintaan akunUntuk alat yang sudah berbicara format ini, lihat Alat dan SDK, dan untuk agen pengkodean seperti Claude Code, Codex dan Cline, lihat Kode Alat.