Shakespeare AI API Documentation

← Home Terms of Service
Base URL: https://ai.shakespeare.diy/v1
Authentication: Nostr NIP-98

Table of Contents

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.5", "object": "model", "created": 1640995200, "owned_by": "shakespeare-ai" }, { "id": "claude-sonnet-4.5", "object": "model", "created": 1640995200, "owned_by": "anthropic" } ] }

Available Models

Model ID Description Context Window Pricing
glm-4.5 High-quality model (GLM-4.5) 128,000 tokens $0.0000015/prompt token
$0.0000075/completion token
claude-sonnet-4.5 Claude Sonnet 4.5 (via OpenRouter) 200,000 tokens $0.000004/prompt token
$0.000016/completion token

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.5, claude-sonnet-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.5", "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.5", "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

Need help? Shakespeare AI is open source. Check the GitLab repository for more information or to report issues.