API Reference

OpenAPI Specification

The complete RavenRouter API is documented using the OpenAPI specification. You can access the specification in JSON format:

• JSON: /openapi.json

These specifications can be used with Swagger UI, Postman, or any OpenAPI-compatible code generator to explore the API or generate client libraries.

Requests

Completions Request Format

Request schema for POST /v1/chat/completions. For a runnable example see the Quickstart.

// POST /v1/chat/completions request body
type ChatCompletionRequest = {
  // Required
  model: string;
  messages: Message[];

  // Sampling
  stream?: boolean;
  max_tokens?: number;
  temperature?: number; // [0, 2]
  top_p?: number; // (0, 1]
  stop?: string | string[];

  // Tool calling
  tools?: Tool[];
  tool_choice?: ToolChoice;

  // Structured outputs
  response_format?: { type: 'json_object' } | {
    type: 'json_schema';
    json_schema: { name: string; schema: object; strict?: boolean };
  };

  // Advanced (forwarded when supported)
  seed?: number;
  frequency_penalty?: number;
  presence_penalty?: number;
};

type Message = {
  role: 'system' | 'user' | 'assistant' | 'tool';
  content: string | ContentPart[];
  name?: string;
  tool_call_id?: string;
};

Headers

Authenticate with your API key in the request header. Set `Authorization: Bearer <API_KEY>` and `Content-Type: application/json` on every request.

Base URL: https://api.ravenrouter.ai

Code Examples

Runnable examples in cURL, Node.js, and Python. Replace `<API_KEY>` with a key from the console and send the request — you are ready to deploy.

curl https://api.ravenrouter.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "model": "DeepSeek-V3.2",
    "messages": [
      { "role": "user", "content": "What is the meaning of life?" }
    ]
  }'

Server-Sent Events (SSE) are supported for all chat models. Send `"stream": true` in your request body. The stream may include comment payloads that should be ignored.

If a model does not support a request parameter (such as `top_k` on some providers), the parameter is ignored. Supported parameters are forwarded to the underlying model API.

Responses

Completions Response Format

RavenRouter normalizes responses to comply with the OpenAI Chat API. `choices` is always an array — each choice contains a `message` property, or a `delta` property when streaming.

type ChatCompletionResponse = {
  id: string;
  object: 'chat.completion' | 'chat.completion.chunk';
  created: number;
  model: string;
  choices: NonStreamingChoice[] | StreamingChoice[];
  usage?: {
    prompt_tokens: number;
    completion_tokens: number;
    total_tokens: number;
  };
};

type NonStreamingChoice = {
  index: number;
  finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error' | null;
  message: {
    role: 'assistant';
    content: string | null;
    tool_calls?: ToolCall[];
  };
};

type StreamingChoice = {
  index: number;
  finish_reason: string | null;
  delta: {
    role?: string;
    content?: string | null;
    tool_calls?: ToolCall[];
  };
};

Example Response

{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "DeepSeek-V3.2",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 9,
    "total_tokens": 21
  }
}

Finish Reason

Each model's `finish_reason` is normalized to one of: `stop`, `length`, `tool_calls`, `content_filter`, or `error`. The raw provider value is available when returned by the upstream.

Usage & Billing

Token counts in the response `usage` field follow the model tokenizer. Credit consumption is reflected in the console usage dashboard. For streaming requests, `usage` is included in the final chunk.

Streaming

Set `"stream": true` on chat completions. The server responds with Server-Sent Events (SSE) chunks compatible with OpenAI clients.

curl https://api.ravenrouter.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "model": "DeepSeek-V3.2",
    "stream": true,
    "messages": [
      { "role": "user", "content": "Write a haiku about APIs." }
    ]
  }'

Rate Limits

Limits depend on your subscription tier (RPM and concurrency). When exceeded, the API returns `429 Too Many Requests`. Retry with exponential backoff.

View your current quota in Console → Usage.

Authentication

Every API call must include your key in the request header: `Authorization: Bearer <API_KEY>`. Create keys in Console → API Keys.

curl https://api.ravenrouter.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "model": "DeepSeek-V3.2",
    "messages": [
      { "role": "user", "content": "What is the meaning of life?" }
    ]
  }'

Never expose API keys in client-side code. Rotate keys immediately if compromised.

Parameters

Chat completion requests accept standard OpenAI-compatible parameters. Unsupported parameters for a given model are silently ignored.

Errors & Debugging

Common HTTP status codes and how to resolve them:

401 Unauthorized

Invalid, disabled, or missing API key.

429 Too Many Requests

Rate or concurrency limit exceeded.

400 Bad Request

Unknown model slug or malformed JSON body.

502 Bad Gateway

Upstream provider error — retry or switch model.

Create Chat Completion

POST `/v1/chat/completions` — POST `/v1/chat/completions` — OpenAI-compatible chat with streaming support via `"stream": true`.

Models

GET `/v1/models` returns the catalog your key can access. Browse the full list at Model APIs.

Images

POST `/v1/images/generations` for text-to-image. Model availability depends on your plan and catalog.