mirror of
https://github.com/Routstr/routstr-core.git
synced 2026-08-09 11:04:36 +00:00
531 lines
9.8 KiB
Markdown
531 lines
9.8 KiB
Markdown
# API Endpoints
|
|
|
|
Complete reference for all Routstr API endpoints.
|
|
|
|
## Overview
|
|
|
|
Routstr provides OpenAI-compatible endpoints with Bitcoin/eCash payment integration.
|
|
|
|
### Base URL
|
|
|
|
All endpoints use the base URL:
|
|
|
|
```text
|
|
https://api.routstr.com/v1
|
|
```
|
|
|
|
### Authentication
|
|
|
|
All endpoints require authentication via:
|
|
|
|
- **Bearer Token**: `Authorization: Bearer sk-...` or `Authorization: Bearer cashuAeyJ0...`
|
|
- **X-Cashu Header**: `X-Cashu: cashuAeyJ0...` (for direct eCash payments)
|
|
|
|
See [Authentication](authentication.md) for details.
|
|
|
|
## Chat
|
|
|
|
### Create Chat Completion
|
|
|
|
Send messages to generate model responses.
|
|
|
|
```http
|
|
POST /v1/chat/completions
|
|
```
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"model": "gpt-4",
|
|
"messages": [
|
|
{
|
|
"role": "system",
|
|
"content": "You are a helpful assistant."
|
|
},
|
|
{
|
|
"role": "user",
|
|
"content": "Hello!"
|
|
}
|
|
],
|
|
"temperature": 0.7,
|
|
"stream": false
|
|
}
|
|
```
|
|
|
|
**Parameters:**
|
|
|
|
| Parameter | Type | Required | Default | Description |
|
|
|-----------|------|----------|---------|-------------|
|
|
| `model` | string | Yes | - | Model ID to use |
|
|
| `messages` | array | Yes | - | Array of message objects |
|
|
| `temperature` | number | No | 1.0 | Sampling temperature (0-2) |
|
|
| `max_tokens` | integer | No | Model default | Maximum tokens to generate |
|
|
| `stream` | boolean | No | false | Stream partial responses |
|
|
| `top_p` | number | No | 1.0 | Nucleus sampling |
|
|
| `n` | integer | No | 1 | Number of completions |
|
|
| `stop` | string/array | No | null | Stop sequences |
|
|
| `presence_penalty` | number | No | 0 | Presence penalty (-2 to 2) |
|
|
| `frequency_penalty` | number | No | 0 | Frequency penalty (-2 to 2) |
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"id": "chatcmpl-123",
|
|
"object": "chat.completion",
|
|
"created": 1677652288,
|
|
"model": "gpt-4",
|
|
"choices": [{
|
|
"index": 0,
|
|
"message": {
|
|
"role": "assistant",
|
|
"content": "Hello! How can I help you today?"
|
|
},
|
|
"finish_reason": "stop"
|
|
}],
|
|
"usage": {
|
|
"prompt_tokens": 13,
|
|
"completion_tokens": 9,
|
|
"total_tokens": 22
|
|
}
|
|
}
|
|
```
|
|
|
|
### Streaming Response
|
|
|
|
When `stream: true`:
|
|
|
|
```text
|
|
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
|
|
|
|
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
|
|
|
|
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
|
|
|
|
data: [DONE]
|
|
```
|
|
|
|
## Completions (Coming Soon)
|
|
|
|
### Create Completion
|
|
|
|
**Note: This endpoint is coming soon and not yet available.**
|
|
|
|
Generate text completion (legacy endpoint).
|
|
|
|
```http
|
|
POST /v1/completions
|
|
```
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"model": "gpt-3.5-turbo-instruct",
|
|
"prompt": "Once upon a time",
|
|
"max_tokens": 50,
|
|
"temperature": 0.7
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"id": "cmpl-123",
|
|
"object": "text_completion",
|
|
"created": 1677652288,
|
|
"model": "gpt-3.5-turbo-instruct",
|
|
"choices": [{
|
|
"text": " in a faraway land, there lived a brave knight...",
|
|
"index": 0,
|
|
"logprobs": null,
|
|
"finish_reason": "length"
|
|
}],
|
|
"usage": {
|
|
"prompt_tokens": 4,
|
|
"completion_tokens": 50,
|
|
"total_tokens": 54
|
|
}
|
|
}
|
|
```
|
|
|
|
## Embeddings
|
|
|
|
### Create Embeddings (Coming Soon)
|
|
|
|
**Note: This endpoint is coming soon and not yet available.**
|
|
|
|
Generate vector representations of text.
|
|
|
|
```http
|
|
POST /v1/embeddings
|
|
```
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"model": "text-embedding-3-small",
|
|
"input": "The quick brown fox jumps over the lazy dog",
|
|
"encoding_format": "float"
|
|
}
|
|
```
|
|
|
|
**Parameters:**
|
|
|
|
| Parameter | Type | Required | Default | Description |
|
|
|-----------|------|----------|---------|-------------|
|
|
| `model` | string | Yes | - | Embedding model ID |
|
|
| `input` | string/array | Yes | - | Text(s) to embed |
|
|
| `encoding_format` | string | No | "float" | Format: "float" or "base64" |
|
|
| `dimensions` | integer | No | Model default | Output dimensions |
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"object": "list",
|
|
"data": [{
|
|
"object": "embedding",
|
|
"index": 0,
|
|
"embedding": [0.0023064255, -0.009327292, ...]
|
|
}],
|
|
"model": "text-embedding-3-small",
|
|
"usage": {
|
|
"prompt_tokens": 9,
|
|
"total_tokens": 9
|
|
}
|
|
}
|
|
```
|
|
|
|
## Images (Coming Soon)
|
|
|
|
### Create Image
|
|
|
|
**Note: This endpoint is coming soon and not yet available.**
|
|
|
|
Generate images from text prompts.
|
|
|
|
```http
|
|
POST /v1/images/generations
|
|
```
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"model": "dall-e-3",
|
|
"prompt": "A white siamese cat wearing a space helmet",
|
|
"n": 1,
|
|
"size": "1024x1024",
|
|
"quality": "standard"
|
|
}
|
|
```
|
|
|
|
**Parameters:**
|
|
|
|
| Parameter | Type | Required | Default | Description |
|
|
|-----------|------|----------|---------|-------------|
|
|
| `model` | string | Yes | - | Model: dall-e-2, dall-e-3 |
|
|
| `prompt` | string | Yes | - | Text description |
|
|
| `n` | integer | No | 1 | Number of images |
|
|
| `size` | string | No | "1024x1024" | Image dimensions |
|
|
| `quality` | string | No | "standard" | Quality: standard, hd |
|
|
| `style` | string | No | "vivid" | Style: vivid, natural |
|
|
| `response_format` | string | No | "url" | Format: url, b64_json |
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"created": 1677652288,
|
|
"data": [{
|
|
"url": "https://generated-image-url.com/image.png",
|
|
"revised_prompt": "A white Siamese cat wearing a detailed space helmet..."
|
|
}]
|
|
}
|
|
```
|
|
|
|
## Audio (Coming Soon)
|
|
|
|
### Create Transcription
|
|
|
|
**Note: This endpoint is coming soon and not yet available.**
|
|
|
|
Convert audio to text.
|
|
|
|
```http
|
|
POST /v1/audio/transcriptions
|
|
Content-Type: multipart/form-data
|
|
```
|
|
|
|
**Form Data:**
|
|
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `file` | file | Yes | Audio file (mp3, mp4, mpeg, mpga, m4a, wav, webm) |
|
|
| `model` | string | Yes | Model ID (whisper-1) |
|
|
| `language` | string | No | Language code (ISO-639-1) |
|
|
| `prompt` | string | No | Context prompt |
|
|
| `response_format` | string | No | Format: json, text, srt, verbose_json, vtt |
|
|
| `temperature` | number | No | Sampling temperature |
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"text": "Hello, this is the transcribed audio content."
|
|
}
|
|
```
|
|
|
|
### Create Translation
|
|
|
|
**Note: This endpoint is coming soon and not yet available.**
|
|
|
|
Translate audio to English.
|
|
|
|
```http
|
|
POST /v1/audio/translations
|
|
Content-Type: multipart/form-data
|
|
```
|
|
|
|
Same parameters as transcription, but always translates to English.
|
|
|
|
## Models
|
|
|
|
### List Models
|
|
|
|
Get available models and pricing.
|
|
|
|
```http
|
|
GET /v1/models
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"object": "list",
|
|
"data": [
|
|
{
|
|
"id": "gpt-3.5-turbo",
|
|
"object": "model",
|
|
"created": 1677610602,
|
|
"owned_by": "openai",
|
|
"permission": [...],
|
|
"root": "gpt-3.5-turbo",
|
|
"parent": null,
|
|
"pricing": {
|
|
"prompt": 0.001,
|
|
"completion": 0.002,
|
|
"unit": "1k tokens"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Wallet Management
|
|
|
|
### Create Wallet (Coming Soon)
|
|
|
|
**Note: This endpoint is coming soon. Currently, you can use Cashu tokens directly as API keys.**
|
|
|
|
Create a new wallet with eCash deposit.
|
|
|
|
```http
|
|
POST /v1/wallet/create
|
|
```
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"cashu_token": "cashuAeyJ0...",
|
|
"admin_key": "optional-admin-key"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"api_key": "sk-1234567890abcdef",
|
|
"admin_key": "radmin_fedcba0987654321",
|
|
"balance": 10000,
|
|
"mint": "https://mint.example.com",
|
|
"unit": "sat"
|
|
}
|
|
```
|
|
|
|
### Check Balance
|
|
|
|
Get current wallet balance.
|
|
|
|
```http
|
|
GET /v1/wallet/balance
|
|
Authorization: Bearer sk-...
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"balance": 8500,
|
|
"currency": "sat",
|
|
"reserved": 0
|
|
}
|
|
```
|
|
|
|
### Top Up Wallet
|
|
|
|
Add funds to existing wallet.
|
|
|
|
```http
|
|
POST /v1/wallet/topup
|
|
Authorization: Bearer sk-...
|
|
```
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"cashu_token": "cashuAeyJ0..."
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"balance": 18500,
|
|
"amount_added": 10000,
|
|
"currency": "sat"
|
|
}
|
|
```
|
|
|
|
### Withdraw Funds
|
|
|
|
Withdraw balance as eCash.
|
|
|
|
```http
|
|
POST /v1/wallet/withdraw
|
|
Authorization: Bearer sk-...
|
|
```
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"amount": 5000,
|
|
"mint": "https://mint.example.com"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"cashu_token": "cashuAeyJ0...",
|
|
"amount": 5000,
|
|
"mint": "https://mint.example.com"
|
|
}
|
|
```
|
|
|
|
## Provider Discovery
|
|
|
|
## Admin Settings
|
|
|
|
These endpoints are protected by the Admin cookie (`admin_password` set to your configured admin password).
|
|
|
|
### Get Settings
|
|
|
|
```http
|
|
GET /admin/api/settings
|
|
```
|
|
|
|
Returns the current application settings (sensitive values may be redacted).
|
|
|
|
### Update Settings
|
|
|
|
```http
|
|
PATCH /admin/api/settings
|
|
Content-Type: application/json
|
|
```
|
|
|
|
Body is a partial JSON of settings fields to update. Validated and persisted to the database.
|
|
|
|
### List Providers
|
|
|
|
Get available upstream providers.
|
|
|
|
```http
|
|
GET /v1/providers
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"providers": [
|
|
{
|
|
"name": "openai",
|
|
"models": ["gpt-4", "gpt-3.5-turbo"],
|
|
"endpoints": ["chat/completions", "completions"],
|
|
"status": "active"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Provider Info
|
|
|
|
Get specific provider details.
|
|
|
|
```http
|
|
GET /v1/providers/{provider_name}
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"name": "openai",
|
|
"display_name": "OpenAI",
|
|
"description": "Official OpenAI API",
|
|
"models": [
|
|
{
|
|
"id": "gpt-4",
|
|
"name": "GPT-4",
|
|
"context_window": 8192,
|
|
"pricing": {
|
|
"prompt": 0.03,
|
|
"completion": 0.06,
|
|
"unit": "1k tokens"
|
|
}
|
|
}
|
|
],
|
|
"endpoints": ["chat/completions", "completions", "embeddings"],
|
|
"features": ["streaming", "function_calling"],
|
|
"status": "active"
|
|
}
|
|
```
|
|
|
|
## Rate Limiting
|
|
|
|
All endpoints are subject to rate limiting:
|
|
|
|
- **Per minute**: 60 requests
|
|
- **Per hour**: 1000 requests
|
|
- **Per day**: 10000 requests
|
|
|
|
Rate limit information is included in response headers.
|
|
|
|
## Next Steps
|
|
|
|
- [Errors](errors.md) - Error handling reference
|
|
- [Authentication](authentication.md) - Auth details
|
|
- [Examples](../user-guide/using-api.md) - Code examples
|