Shakespeare AI API Documentation
Base URL: https://ai.shakespeare.diy/v1
Authentication: Nostr NIP-98
Authentication
Shakespeare AI uses Nostr NIP-98 authentication instead of traditional
API keys. All requests must be signed using your Nostr private key.
Using with OpenAI SDK
import { NIP98Client } from "@nostrify/nostrify";
import OpenAI from "openai";
function createShakespeareAI(signer: NostrSigner): OpenAI {
return new OpenAI({
baseURL: "https://ai.shakespeare.diy/v1",
apiKey: "", // Not needed for NIP-98
dangerouslyAllowBrowser: true,
fetch(input, init) {
const client = new NIP98Client({ signer });
return client.fetch(input, init);
},
});
}
Models
List Available Models
GET /v1/models
Returns a list of available models and their specifications.
Response
{
"object": "list",
"data": [
{
"id": "glm-4.6",
"object": "model",
"created": 1640995200,
"owned_by": "system"
},
{
"id": "claude-sonnet-4.5",
"object": "model",
"created": 1640995200,
"owned_by": "system"
}
]
}
Chat Completions
Create Chat Completion
POST /v1/chat/completions
Creates a completion for the chat message. Compatible with OpenAI's chat
completions API.
Request Body
| Parameter |
Type |
Required |
Description |
model |
string |
Yes |
Model to use (glm-4.6, claude-sonnet-4.5, claude-opus-4.5) |
messages |
array |
Yes |
Array of message objects |
temperature |
number |
No |
Sampling temperature (0-2) |
max_tokens |
integer |
No |
Maximum tokens to generate |
stream |
boolean |
No |
Whether to stream responses |
Example Request
{
"model": "glm-4.6",
"messages": [
{
"role": "user",
"content": "Hello, how are you?"
}
],
"temperature": 0.7,
"max_tokens": 150
}
Example Response
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1640995200,
"model": "glm-4.6",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! I'm doing well, thank you for asking..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 20,
"total_tokens": 30
}
}
Credit Management
Note: Credit management endpoints require NIP-98
authentication. Premium models require credits, while free models (like
Tybalt) don't consume credits.
Get Credit Balance
GET /v1/credits
Retrieves the user's current credit balance.
Response
{
"object": "credits",
"amount": 10.50
}
Add Credits
POST /v1/credits/add
Initiates a payment to add credits to the user's account. Supports
Stripe and Lightning Network payments.
Request Body (Stripe)
{
"amount": 10.00,
"method": "stripe",
"redirect_url": "https://yourapp.com/payment/complete"
}
Request Body (Lightning)
{
"amount": 10.00,
"method": "lightning"
}
Response
{
"object": "payment",
"id": "pi_abc123",
"status": "pending",
"amount": 10.00,
"fee": 1.00,
"total": 11.00,
"method": "stripe",
"description": "Credit purchase via Stripe",
"url": "https://checkout.stripe.com/pay/cs_...",
"created_at": 1640995200,
"expires_at": 1640999800
}
Check Payment Status
GET /v1/credits/payments/{payment_id}
Checks the status of a payment. Payments are automatically completed via
webhooks when successful.
List Payments
GET /v1/credits/payments
Retrieves a paginated list of payments for the user.
Query Parameters
| Parameter |
Type |
Description |
limit |
integer |
Maximum number of payments to return (default: 20, max: 100)
|
starting_after |
string |
Payment ID for pagination |
status |
string |
Filter by status: pending, completed, failed, expired |
method |
string |
Filter by method: stripe, lightning |
Error Handling
Shakespeare AI uses standard HTTP status codes and returns errors in
OpenAI-compatible format.
Common Error Codes
| HTTP Status |
Error Code |
Description |
| 401 |
unauthorized |
Invalid or missing NIP-98 authentication |
| 400 |
invalid_request_error |
Invalid request format or parameters |
| 429 |
insufficient_quota |
Insufficient credits for premium models |
| 500 |
api_error |
Internal server or upstream provider error |
Error Response Format
{
"error": {
"type": "insufficient_quota",
"code": "insufficient_credits",
"message": "You have insufficient credits for this request",
"param": null
}
}
Credit Management Error Codes
-
minimum_amount_not_met - Payment amount below minimum
threshold
unsupported_method - Payment method not supported-
missing_required_parameter - Required parameter missing
payment_not_found - Payment ID not foundpayment_expired - Payment has expired
Need help? Shakespeare AI is open source. Check the
GitLab repository for more information or to report issues.