OpenAI API Reference

All /v1/* endpoints supported by the SBproxy AI Gateway

Overview

SBproxy's AI Gateway exposes an OpenAI-compatible REST API. Any application or SDK that works with the OpenAI API can connect to SBproxy by changing the base URL. The gateway translates requests to the appropriate provider format automatically.

Setup

To use the AI Gateway endpoints, configure an origin with the ai_proxy action type:

proxy:
  http_bind_port: 8080

origins:
  "ai.example.com":
    action:
      type: ai_proxy
      providers:
        - name: openai
          api_key: sk-your-openai-key
          models: [gpt-4o, gpt-4o-mini]
      default_model: gpt-4o-mini
      routing:
        strategy: fallback_chain
    authentication:
      type: api_key
      api_keys:
        - sb-my-gateway-key

Test it:

curl -H "Host: ai.example.com" -H "Authorization: Bearer sb-my-gateway-key" http://localhost:8080/v1/chat/completions   -H "Content-Type: application/json"   -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}'

Start the proxy and send requests to http://localhost:8080/v1/* with the host header or configure DNS to point ai.example.com to your SBproxy instance.

Try it with test.sbproxy.dev

To test without a real provider, use test.sbproxy.dev as a mock OpenAI backend:

proxy:
  http_bind_port: 8080

origins:
  "ai.example.com":
    action:
      type: ai_proxy
      providers:
        - name: openai
          api_key: test-key
          base_url: https://test.sbproxy.dev
          models: [test-model]
      default_model: test-model
curl -H "Host: ai.example.com" http://localhost:8080/v1/chat/completions   -H "Content-Type: application/json"   -d '{"model": "test-model", "messages": [{"role": "user", "content": "Hello"}]}'

Base URL

http://localhost:8080/v1

Or if deployed with a public hostname: https://ai.example.com/v1

Authentication

Authorization: Bearer sb-my-gateway-key

Gateway API keys are configured in the authentication section of your origin config.

POST /v1/chat/completions

Generate a chat completion from a list of messages. This is the primary endpoint for conversational AI. Supports streaming via "stream": true.

Request Format

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Explain API gateways in one sentence." }
  ],
  "temperature": 0.7,
  "max_tokens": 256,
  "stream": false
}

Key Features

  • Streaming and non-streaming modes
  • Automatic provider translation across 72 native providers (Anthropic, Google Gemini, Mistral, Bedrock, and more)
  • Context window validation rejects oversized requests before they reach the provider
  • Response headers include token counts, cost estimate, latency, and provider used

POST /v1/completions

Legacy text completions endpoint. Accepts a single prompt string and returns one or more completions. Maintained for backward compatibility with older integrations.

Request Format

{
  "model": "gpt-4o-mini",
  "prompt": "The capital of France is",
  "max_tokens": 32,
  "temperature": 0
}

Key Features

  • Single-prompt text completion
  • Supports n parameter for multiple completions per request
  • Same routing and rate limiting as chat completions

POST /v1/responses

Multi-turn conversation endpoint with automatic context management. Clients chain responses together using previous_response_id instead of resending full message history. The gateway stores conversation context with a configurable TTL.

Request Format

{
  "model": "gpt-4o",
  "input": "What was the previous topic?",
  "previous_response_id": "resp_abc123"
}

Key Features

  • Automatic conversation history management
  • Cross-provider support with transparent format translation
  • Agentic workflow support with tool-use patterns
  • Full feature parity with chat completions (routing, rate limiting)

GET /v1/models

List all models available through the gateway. Returns models from every configured provider, merged into a single list. Useful for populating model selectors in client applications.

Request Format

GET /v1/models
Authorization: Bearer sb-your-gateway-key

Key Features

  • Aggregates models across all configured providers
  • Respects gateway key model restrictions - only shows models the key can access
  • Compatible with OpenAI SDK client.models.list()

POST /v1/embeddings

Generate vector embeddings for text input. Used for semantic search, clustering, and retrieval-augmented generation (RAG) pipelines.

Request Format

{
  "model": "text-embedding-3-small",
  "input": "SBproxy is an API gateway."
}

Key Features

  • Single string or array of strings as input
  • Provider-agnostic - works with OpenAI, Cohere, Voyage, and other embedding providers
  • Dimensions parameter supported for models that allow truncation

POST /v1/images/generations

Generate images from text prompts. Routes to configured image generation providers.

Request Format

{
  "model": "dall-e-3",
  "prompt": "A watercolor painting of a mountain at sunset",
  "size": "1024x1024",
  "n": 1
}

Key Features

  • Supports multiple image sizes and quality settings
  • Routes to DALL-E, Stable Diffusion, and other configured providers
  • Rate limiting applies per image request

POST /v1/audio/transcriptions

Transcribe audio files to text. Accepts common audio formats and returns a text transcript.

Request Format

POST /v1/audio/transcriptions
Content-Type: multipart/form-data

file: (audio file)
model: whisper-1
language: en

Key Features

  • Multipart form upload for audio files
  • Optional language hint for improved accuracy
  • Supports response formats: json, text, verbose_json, srt, vtt

POST /v1/audio/speech

Convert text to speech audio. Returns an audio file in the requested format.

Request Format

{
  "model": "tts-1",
  "input": "Welcome to SBproxy.",
  "voice": "alloy"
}

Key Features

  • Multiple voice options per provider
  • Configurable audio output format and speed
  • Streaming audio delivery for low-latency playback

POST /v1/rerank

Rerank a list of documents by relevance to a query. Used in search and RAG pipelines to improve retrieval quality before passing context to a language model.

Request Format

{
  "model": "rerank-v3",
  "query": "How do I configure rate limiting?",
  "documents": [
    "Rate limiting controls request volume...",
    "Caching reduces backend load...",
    "Authentication verifies identity..."
  ],
  "top_n": 3
}

Key Features

  • Relevance scoring for document retrieval pipelines
  • Configurable top_n to limit returned results
  • Works with Cohere, Jina, and other reranking providers

POST /v1/batches

Submit a batch of requests for asynchronous processing. Batch requests are queued and processed at lower priority, often at reduced cost compared to real-time requests.

Request Format

{
  "input_file_id": "file-abc123",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h"
}

Key Features

  • Asynchronous processing for high-volume workloads
  • Lower cost per request compared to synchronous endpoints
  • Status polling and result retrieval via batch ID

POST /v1/fine_tuning/jobs

Create and manage fine-tuning jobs. Upload training data and launch model customization through the gateway.

Request Format

{
  "model": "gpt-4o-mini-2024-07-18",
  "training_file": "file-abc123",
  "hyperparameters": {
    "n_epochs": 3
  }
}

Key Features

  • Job lifecycle management: create, list, retrieve, cancel
  • Training event streaming for progress monitoring
  • Rate limiting applies to fine-tuning spend tracking

Response Headers

Every AI Gateway response includes additional headers for observability:

  • X-Request-ID - Unique request identifier for end-to-end tracing
  • X-Provider - The provider that served the request
  • X-Model - The actual model used (may differ from requested if routed)
  • X-Tokens-Input - Input token count
  • X-Tokens-Output - Output token count
  • X-Cost - Estimated cost in USD
  • X-Latency-Ms - Provider response time in milliseconds

Error Format

Errors follow the OpenAI error format for SDK compatibility:

{
  "error": {
    "message": "Rate limit exceeded for model gpt-4o",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

Common error codes: rate_limit_exceeded, context_length_exceeded, model_not_found, provider_error.

← PreviousOverviewNext →Model Routing