API Documentation
Version: 1.0.0
Endpoints
| Path | Method | Description | Auth Required |
|---|---|---|---|
/v1/chat/completions | POST | Chat completions with multi-provider intelligent routing (OpenAI-compatible) | No |
/v1/responses | POST | OpenAI Responses API endpoint (for n8n v2.1+ and modern OpenAI clients) | No |
/v1/models | GET | List all available models and aliases | No |
/v1/models/{model} | GET | Get details for a specific model | No |
/health | GET | System health check and component status | No |
/metrics | GET | System metrics and performance data | No |
/model-health | GET | Model availability and circuit breaker status | No |
/help | GET | API documentation and usage information (this endpoint) | No |
/v1/help | GET | API documentation (alias for /help) | No |
Intelligent Routing
Use these keywords as the model parameter for automatic optimization:
- fast: Optimizes for speed (lowest latency models, excludes flex-tier)
- fast-flex: Fast routing with OpenAI flex-tier pricing
- balanced: Balances cost, speed, and quality (default)
- balanced-flex: Balanced routing with OpenAI flex-tier pricing
- quality: Prioritizes output quality (best available models)
- cost: Minimizes cost (cheapest available models)
- speed: Fastest response time (alias for "fast")
- @n8n/n8n-nodes-langchain.openAi v1.x (Chat Completions API)
- @n8n/n8n-nodes-langchain.openAi v2.1+ (Responses API)
- Legacy: /v1/chat/completions - Used by n8n OpenAI node v1.x
- Modern: /v1/responses - Used by n8n OpenAI node v2.1+
Available Models
| Model ID | Provider | Context Limit | Input (per 1M) | Output (per 1M) |
|---|---|---|---|---|
gpt-5 | openai | 400,000 | $1.25 | $10.00 |
gpt-5-mini | openai | 400,000 | $0.25 | $2.00 |
gpt-5-nano | openai | 400,000 | $0.05 | $0.40 |
gpt-5.1 | openai | 400,000 | $1.25 | $10.00 |
gpt-5.1-codex | openai | 400,000 | $1.25 | $10.00 |
gpt-5.2 | openai | 400,000 | $1.75 | $14.00 |
gpt | openai | 400,000 | $1.75 | $14.00 |
gpt-mini | openai | 400,000 | $0.25 | $2.00 |
gpt-nano | openai | 400,000 | $0.05 | $0.40 |
gpt-flex | openai | 400,000 | $0.88 | $7.00 |
gpt-mini-flex | openai | 400,000 | $0.13 | $1.00 |
gpt-nano-flex | openai | 400,000 | $0.03 | $0.20 |
sonnet-4-5 | anthropic | 200,000 | $3.00 | $15.00 |
haiku-4-5 | anthropic | 200,000 | $1.00 | $5.00 |
sonnet | anthropic | 200,000 | $3.00 | $15.00 |
haiku | anthropic | 200,000 | $1.00 | $5.00 |
claude-sonnet-4-5 | anthropic | 200,000 | $3.00 | $15.00 |
claude-haiku-4-5 | anthropic | 200,000 | $1.00 | $5.00 |
claude-sonnet-4-5-20250929 | anthropic | 200,000 | $3.00 | $15.00 |
claude-haiku-4-5-20251001 | anthropic | 200,000 | $1.00 | $5.00 |
gemini-2.5-pro | 1,048,576 | $1.25 | $5.00 | |
gemini-2.5-flash | 1,048,576 | $0.15 | $0.60 | |
gemini-2.5-flash-lite | 1,048,576 | $0.07 | $0.30 | |
gemini-2.0-flash | 1,000,000 | $0.10 | $0.40 | |
gemini-2.0-flash-lite | 1,000,000 | $0.06 | $0.25 | |
gemini-3-pro-preview | 1,000,000 | $2.00 | $12.00 | |
gemini-3-flash-preview | 1,000,000 | $0.50 | $3.00 | |
imagen-3 | 0 | N/A | N/A | |
imagen-3-fast | 0 | N/A | N/A | |
gemini | 1,000,000 | $0.50 | $3.00 | |
gemini-pro | 1,000,000 | $2.00 | $12.00 | |
gemini-flash | 1,000,000 | $0.50 | $3.00 | |
gemini-flash-lite | 1,048,576 | $0.07 | $0.30 | |
gemini-2.5-pro-latest | 1,048,576 | $1.25 | $5.00 | |
gemini-2.5-flash-latest | 1,048,576 | $0.15 | $0.60 |
Model Aliases
| Alias | Target Model |
|---|---|
gpt | gpt-5.2 |
gpt-mini | gpt-5-mini |
gpt-nano | gpt-5-nano |
gpt-flex | gpt-5.2 |
gpt-mini-flex | gpt-5-mini |
gpt-nano-flex | gpt-5-nano |
sonnet | sonnet-4-5 |
haiku | haiku-4-5 |
claude-sonnet-4-5 | sonnet-4-5 |
claude-haiku-4-5 | haiku-4-5 |
claude-sonnet-4-5-20250929 | sonnet-4-5 |
claude-haiku-4-5-20251001 | haiku-4-5 |
gemini | gemini-3-flash-preview |
gemini-pro | gemini-3-pro-preview |
gemini-flash | gemini-3-flash-preview |
gemini-flash-lite | gemini-2.5-flash-lite |
gemini-2.5-pro-latest | gemini-2.5-pro |
gemini-2.5-flash-latest | gemini-2.5-flash |
gemini-3-pro-preview | gemini-3-pro-preview |
gemini-3-flash-preview | gemini-3-flash-preview |
Authentication
Optional: Include "Authorization: Bearer
Example with Authorization Header
``bash
curl -X POST https://universal.sparkry.ai/v1/chat/completions \\
-H "Authorization: Bearer YOUR_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"model": "gpt",
"messages": [
{"role": "user", "content": "Hello!"}
]
}'
`
Examples
Basic chat completion request
`bash
curl -X POST https://universal.sparkry.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "gpt",
"messages": [
{"role": "user", "content": "Hello!"}
]
}'
`
Request with specific model
`bash
curl -X POST https://universal.sparkry.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4",
"messages": [
{"role": "user", "content": "Explain quantum computing"}
]
}'
`
Streaming response
`bash
curl -X POST https://universal.sparkry.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "gpt",
"messages": [
{"role": "user", "content": "Write a story"}
],
"stream": true
}'
``
n8n Integration
Full compatibility with n8n workflow automation. Supports both legacy and modern OpenAI nodes.
Supported Nodes
Endpoints
Setup
In n8n, create an OpenAI credential with Base URL set to https://openai-llm.sparkst.workers.dev (no /v1 suffix). Use any of our supported models (gpt, balanced, claude-sonnet-4, etc.) in the model field.