API contract work sample · Unofficial, mock data
API Reference
OpenAI-compatible. One key, one balance. Provider fallback built in.
Base URL
https://api.sub2api.com/v1All requests use HTTPS. The base URL is OpenAI-compatible — change the host and your existing SDK code works.
Authentication
All requests require a Bearer token. Get your API key from the Dashboard → API Keys.
Authorization: Bearer $SUB2API_KEYKeep your key secret. Rotate it anytime from the dashboard. Requests without a valid key receive 401 invalid_api_key.
Quickstart
Contract-accurate example. This shows the full request and response shape — not a live endpoint.
Request
curl https://api.sub2api.com/v1/chat/completions \
-H "Authorization: Bearer $SUB2API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Hello"}]
}'Chat Completions
POST /v1/chat/completions
OpenAI-compatible chat endpoint. The response includes Sub2API-specific fields: provider, routing, fallback, and billing.
Request body
{
"model": "gpt-4o", // required — model ID from /v1/models
"messages": [ // required
{"role": "user", "content": "Hello"}
],
"provider": "auto", // optional — "auto" or specific provider id
"fallback": true, // optional — default true
"max_tokens": 1024, // optional
"temperature": 0.7 // optional
}Response
{
"id": "chatcmpl-9a8b7c6d5e4f",
"object": "chat.completion",
"model": "gpt-4o",
"provider": "openai",
"routing": "auto",
"fallback": false,
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"content": "Hi! How can I help you today?"
},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 8,
"completion_tokens": 9,
"total_tokens": 17
},
"billing": {
"credits_used": 0.04,
"balance_after": 18.73,
"currency": "USD"
}
}List Models
GET /v1/models
Returns available models with provider, pricing, and status.
{
"object": "list",
"data": [{
"id": "gpt-4o",
"provider": "openai",
"status": "live",
"pricing": {
"input": 2.50,
"output": 10.00,
"unit": "per 1M tokens"
}
}, {
"id": "claude-sonnet-4-6",
"provider": "anthropic",
"status": "live",
"pricing": {
"input": 3.00,
"output": 15.00,
"unit": "per 1M tokens"
}
}]
}Usage
GET /v1/usage
Returns current billing period usage summary. Accepts optional ?days=7 or ?days=30.
{
"period": "2026-06-01 to 2026-06-26",
"total_credits_used": 12.84,
"total_requests": 342,
"by_model": [{
"model": "gpt-4o",
"requests": 210,
"credits_used": 8.15
}, {
"model": "claude-sonnet-4-6",
"requests": 98,
"credits_used": 3.92
}],
"balance_remaining": 18.73
}Error Codes
| Status | Code | Meaning |
|---|---|---|
| 401 | invalid_api_key | API key missing or invalid |
| 402 | insufficient_balance | Not enough credits. Top up from the dashboard. |
| 429 | rate_limited | Too many requests. Check the Retry-After header. |
| 503 | provider_unavailable | Provider is down and no fallback is available. |
| 500 | internal_error | Something went wrong on our side. We're on it. |
Rate Limits
| Plan | Requests / min | Tokens / min |
|---|---|---|
| Free | 10 | 10,000 |
| Starter | 100 | 200,000 |
| Pro | 1,000 | 2,000,000 |
Exceeded limits return 429 rate_limited. Check the Retry-After response header for the wait time in seconds.
Billing Fields
Every API response that consumes credits includes a billing object. No separate dashboard call needed to track spend.
{
"billing": {
"credits_used": 0.42, // credits consumed by this request
"balance_after": 18.73, // remaining balance after this request
"currency": "USD", // billing currency
"model": "gpt-4o", // model used for this request
"provider": "openai", // provider that served this request
"routing": "auto" // routing mode: "auto" or "manual"
}
}