Base de connaissances / Développeurs

Vue d'ensemble du feu

Les modèles, les générateurs et les équilibres que vous utilisez dans l'application, à partir de votre propre code. L'API parle les formats OpenAI et Anthropic, de sorte que la plupart des outils et des SDK fonctionnent en modifiant une URL de base et une clé.

Cette page est traduite automatiquement pour plus de commodité. La version originale anglaise est la version qui s’applique.

Qu’est-ce que le feu

Une API HTTP nymbot.ai qui répond aux mêmes demandes que celles déjà envoyées par un client OpenAI ou Anthropic.

• Chat complémentaireet le Réponse à API et Messages anthropologiques, avec le streaming, les outils, les images, le raisonnement et la recherche web, pour chaque modèle dans le Catalogue et pour le routage automatique de Nymbot lui-même.
• Images, Vidéo, Discours, Transcription et Les embeddings.
• Ton équilibre, Lumière Top-ups, Top-ups automatiques de votre portefeuille et a Histoire le coût de chaque demande.

Il est payé par les deux mêmes équilibre Il n’y a pas d’abonnement et pas de cotisation gratuite sur l’API : chaque demande est payée à partir des crédits que vous avez achetés.

Ce que l'API ne fait pas, c'est d'ajouter quelque chose de Nymbot lui-même. Vos messages vont au modèle alors que vous les avez envoyés: pas de prompt système Nymbot, pas de mémoire, pas de date ou d'indices de langue.

URL de base

Tous les endroits vivent sous /api/v1/Un chemin inconnu revient 404 et un chemin connu appelé avec la mauvaise méthode revient 405Tout comme JSON.

L'API répond aux demandes d'origine croisée de n'importe quel site, de sorte qu'une page de navigateur peut l'appeler. Tout ce que vous envoyez à un navigateur peut être lu par quiconque l'ouvre, cependant, alors ne le faites que avec une clé qui a un petit CapLes endpoints signés avec votre nym (clés, résumé du compte, NWC auto-top-up et remboursement de remboursement) sont l’exception : dans un navigateur, ils ne répondent qu’aux sites de Nymbot. Signature des demandes de compte.

Envoyer chaque corps JSON avec Content-Type: application/jsonTout autre type est refusé 415Un format HTML ou un text/plain requête d'un autre site ne peut pas atteindre l'API. Avec cURL, passer -H "Content-Type: application/json" En même temps avec -d.

Les clés de feu

Les clés sont créées dans l'application.Open Le feu dans la barre latérale de l'application web, ou dans le menu sur Android et iOS, et appuyez sur Créer une cléDonnez-lui un nom et, si vous le souhaitez, un cap et une date d’expiration.

Copiez-le quelque part en toute sécurité avant de fermer la feuille : Nymbot ne conserve qu'une empreinte digitale de celle-ci, de sorte qu'elle ne puisse plus vous la montrer.

Une clé semble sk-nymbot- suivie de 43 lettres, chiffres, dalles et sous-titres. L'application liste chaque clé par son nom et une petite indication telle que sk-nymbot-Qm7x…c2Lw.

• Une clé appartient à votre nym. Il dépense votre solde, et seul votre nym peut le faire, le changer ou le révoquer.Quiconque détient la clé peut le dépenser, alors traitez-le comme un mot de passe.
• Les caps sont en mise. Une clé peut avoir un plafond de dépenses, et le plafond peut être réinitialisé tous les jours, chaque semaine (lundi) ou chaque mois (le premier), à 00:00 UTC. Il compte les deux soldes, un crédit standard comme 10 sats et un crédit Pro comme 100, de sorte qu'il signifie la même chose quel que soit le solde qu'une demande dépense. Avant qu'une demande ne fonctionne, le maximum qu'elle pourrait coûter (enroulé à des crédits entiers) est défini contre ce qui reste du plafond. 403 key_limit_reached, même si la réponse serait entrée sous le cap ; l'erreur indique combien reste et quand le cap est réinitialisé. max_tokens Une demande est facturée ce qu'elle coûte réellement et cela compte contre le cap, donc si le fournisseur rapporte plus de jetons que ceux qui ont été mis de côté, la dernière demande qui correspond peut prendre la clé un peu au-delà de son cap ; la prochaine est alors refusée.
• Un cap dépensé ne fait qu’arrêter la dépense. Une clé à son cap peut toujours vérifier le solde, lire son historique, énumérer les modèles, compter les jetons, enregistrer et vérifier une vidéo qu’elle a déjà commencée.
• L’expiration est optionnelle. Après la date que vous avez définie, la clé cesse de fonctionner.
• La révocation est immédiate et définitive. Une clé révoquée échoue à sa prochaine demande. Elle reste dans la liste, marquée révoquée, de sorte que son historique de dépenses a encore du sens.
• Vous pouvez avoir jusqu'à 25 clés actives, chacune ayant son propre nom. Modifier la période de réinitialisation d'une clé commence une nouvelle période à zéro.

La même feuille montre les dépenses de chaque clé pendant cette période et au total, quand elle a été utilisée pour la dernière fois, vos soldes et vos demandes d'API récentes. Gestion des clés.

Authentication d’une demande

Envoyez la clé dans l'une de ces en-têtes. Ils sont équivalents, alors utilisez ce que votre client envoie par défaut:

Retour de clés manquantes, inconnues, révoquées ou expirées 401Avec le code missing_api_key, invalid_api_key, revoked_api_key ou expired_api_keyLa liste des modèles, des modèles audio et des voix et des méthodes de paiement n'ont pas besoin de clé.

Des images, des vidéos, des discours, des transcriptions et des embeddings peuvent également être payés pour une demande à la fois sur Lightning sans clé du tout: envoyer la demande sans une et payer la facture dans le 402 Réponse : voir Payer sur demande sans clé.

La gestion des clés, le résumé du compte et les top-ups automatiques sont l'exception: ils prennent une signature de votre nym au lieu d'une clé, de sorte qu'une clé fuit ne peut pas faire plus de clés. Signature des demandes de compte.

Votre première demande

Mettez la clé dans une variable d'environnement, puis demandez à un modèle quelque chose. 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 est le propre routage de Nymbot, payé à partir du solde standard. Mettez l'identifiant d'un modèle de catalogue là-bas, par exemple anthropic/claude-sonnet-5, pour utiliser ce modèle de l'équilibre Pro. Liste des modèles Donner chaque identité.

Combien coûte une demande

L'API facture exactement comme l'application le fait.

• Quel équilibre ! nymbot/auto dépenser les normes balance (10 sats un crédit). Chaque autre modèle de chat dépense le pour Le générateur d'image standard et la voix standard dépensent des crédits standards; chaque autre générateur dépense Pro. Les embeddings dépensent des crédits standards. La transcription dépense des crédits standards lorsque le solde standard peut le couvrir, et les crédits Pro autrement. La liste des modèles indique quel solde dépense chaque modèle.
• Combien de . Une demande de chat est mesurée sur les jetons que le modèle a effectivement lu et écrit, aux tarifs publiés du fournisseur. Ce prix a une taxe de 5% ajoutée et est ensuite multiplié par 1,5, de sorte que vous payez 1 575 fois le prix de la liste du fournisseur. Il est converti en sats au prix Bitcoin en direct et facturé en milliers d'un crédit. Les images pro, la vidéo et la parole sont tarifiées par génération, par seconde ou par caractère, et la transcription par seconde d'audio, avec la même taxe et la même marge. L'image standard est un plat 5 crédits standards et la voix standard un plat 3.
• Le minimum ! Chaque demande mesurée qui fonctionne coûte au moins 0,05 crédit: une moitié sur le solde standard, 5 mises sur Pro. Les fractions d'un crédit sont transférées, pas arrondies à chaque fois.
• Maintenez, puis assurez vous. Avant d'exécuter une demande, le plus de coûts qu'elle pourrait coûter est détenu de votre solde, en fonction de ce que vous avez envoyé et du plus de jetons qu'il peut écrire. Le texte en dehors de l'ASCII ordinaire est dimensionné à partir de ses octets UTF-8, et les chiffres ASCII et la ponctuation comptent comme un jeton chacun, de sorte que le texte dans n'importe quel script, code et chiffres sont conservés en totalité. Le hold est en crédits entiers, au moins un, de sorte que toute demande a besoin d'au moins 10 lots gratuits sur le solde standard ou 100 lots sur Pro pour démarrer. Seul le coût réel est facturé; le reste est libéré lorsqu'il est terminé. Une longue demande conserve sa 402 insufficient_balance Si le coût réel est supérieur à ce que le solde peut payer, le solde entier est pris, le reste est dû (owed_sats Dans le nymbot Objet, et un solde négatif). Ce qui est dû est payé d'abord à partir des crédits suivants qui atteignent ce solde. Jusqu'à ce qu'il soit payé, rien sur ce solde ne peut être dépensé: pas par l'API, répond dans l'application, un transfert ou un cadeau.
• Pas assez de crédit. Si le solde ne peut couvrir la détention, la demande est rejetée avec 402 L'erreur indique quel solde est court, combien de lots la demande a besoin et combien sont gratuits. max_tokens Cela signifie une plus petite prise.
• des échecs. Une demande qui échoue ne coûte rien, sauf si le fournisseur a facturé pour le travail qu'il a fait avant d'échouer, ou une recherche sur le web ou le nymbot/auto Un flux que vous coupez est facturé pour les jetons que le fournisseur rapporte: Nymbot continue de lire le flux du fournisseur jusqu'à 25 secondes après que vous quittez pour obtenir ce comptage.
• Recherche web coûte 0,008 $ une recherche, convertie en sats, chaque fois qu'une recherche a été effectuée, que le modèle réponde ou échoue.

Chaque réponse indique combien elle coûte. les réponses JSON nymbot objet avec le solde à partir duquel il a été payé, la charge en crédits et en sats, et ce qui reste:

Objet de coût

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

Les réponses payées portent également ces en-têtes, ce qui est l'endroit où rechercher le coût d'une réponse qui n'est pas JSON, telle que la parole:

Les taux par million de jetons, déjà incluant les frais et la marge, sont dans le Liste des modèles en dollars et en taux, et sur La feuille de prixSi le prix Bitcoin ne peut pas être lu, les demandes payées retournent 503 price_unavailable avec Retry-After: 60 Au lieu de deviner.

erreurs

Chaque erreur a la même forme, celle que les clients OpenAI comprennent déjà. code est un nom stable sur lequel vous pouvez correspondre; message C’est pour les gens et ça peut changer.

Corps erroné

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

Deux exceptions :

• /api/v1/messages réponses dans le format d'erreur d'Anthropic, car c'est ce que les clients d'Anthropic analysent: {"type": "error", "error": {"type": "authentication_error", "message": "…"}}Le type suit le statut : 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).
• Une demande de streaming qui échoue avant son premier octet reçoit une erreur JSON ordinaire avec l'état ci-dessus, pas un flux d'événements.

Les messages d'erreur ne contiennent jamais les détails internes d'un autre service. L'erreur d'un fournisseur est réformulée avant qu'elle ne vous parvienne.

limites

Un lien vers une image doit indiquer un hébergeur public : une adresse sur un réseau privé ou local, ou sur les sites de Nymbot, est refusée.Le rythme du fournisseur qui s’applique dans l’application s’applique également ici, de sorte qu’une explosion de demandes à un fournisseur peut être ralentie plutôt qu’échouée.

Ce que le feu peut voir

L'API n'est pas privée de la manière dont les applications sont, et il vaut la peine d'être précis sur la façon dont.

• Il n’est pas crypté de bout en bout. Dans les applications, un message est scellé sur votre appareil à des clés que Nymbot détient et voyage comme un Cadeau WrapUne demande API est HTTPS ordinaire : elle est cryptée sur le chemin de Nymbot, et le serveur de Nymbot la lit dans le clair pour la gérer.
• Les appels et réponses ne sont pas enregistrés. Ce qui est conservé est la facture : pour chaque demande, le temps, le modèle, le type, les comptes de jetons, le coût, le solde, la clé et si elle a réussi, pendant 90 jours, ce qui est Recherche Histoire Un registre d'utilisation de la même demande (temps, type, modèle, nombre de jetons, coût, durée et si elle a utilisé la recherche sur le web ou a réussi) est également conservé pendant 90 jours, aux côtés de celle de l'application.
• Tout le reste tenu pour un nym est petit et énuméré ici. Les clés de feu sont stockés comme un hash, jamais la clé, avec leur nom, une petite suggestion, une limite de dépenses, une période de réinitialisation, l'expiration et quand ils ont été faits et utilisés pour la dernière fois; seules les 50 dernières clés révoquées sont conservées. Top-up automatique La connexion de portefeuille est stockée cryptée, avec son seuil, son montant et le résultat du dernier top-up. Les emplois vidéo sont conservés pendant 24 heures. Les demandes payées par appel ne laissent qu'un hash de paiement Lightning pendant 7 jours et un jeton de remboursement hashé pendant 30 jours, lié à aucun nym.
• En supprimant l’application, il est supprimé. A Dispositif WIPE révoque et supprime chaque clé API, et supprime l'historique des requêtes, les enregistrements d'utilisation, la connexion de portefeuille et les emplois vidéo.
• Le fournisseur du modèle voit votre demandeLes modèles de catalogue s’exécutent chez leurs fabricants ; les itinéraires et embeddings standard s’exécutent sur Cloudflare.
• Les médias générés sont publics. Les images et vidéos livrées sous forme de liens sont téléchargées sur les hôtes de fichiers public Blossom, où l'adresse d'un fichier est son hash. Toute personne avec le lien peut l'ouvrir, et Nymbot ne peut pas le télécharger à nouveau. b64_json et une image générée revient dans la réponse et n'est jamais téléchargée.
• Ce sont les images que vous donnez à un générateur. Une image que vous téléchargez Edit, ou envoyer comme a data: URL dans un générateur image_url, est téléchargé sur un hôte public Blossom d'abord afin que le générateur puisse le récupérer, et la même chose s'applique. https:// Les images dans une demande de chat vont au fournisseur du modèle, pas à Blossom.
• Une clé est liée à votre nym. Tout ce qu'une clé dépense vient de votre solde, donc l'utilisation de l'API n'est pas AnonymeSi vous voulez que l'utilisation de l'API soit gardée à l'écart de votre nym quotidien, faites les clés d'une nym séparée avec son propre équilibre.

Si vous avez besoin de la protection des applications, utilisez les applications.L'API est pour lorsque vous avez besoin des modèles dans vos propres outils.

Tous les endpoints

“Nym” signifie une demande signée par votre clé Nostr, décrite dans Signature des demandes de comptePour les outils qui parlent déjà de ces formats, voir Outils et SDK, et pour les agents de codage tels que Claude Code, Codex et Cline, voir Outils de codage.