Allgate
Start free

API REFERENCE

OpenAI-compatible · one base URL for every capability

Point your base_url at Allgate and swap in an Allgate API key — existing OpenAI SDKs keep working across every model and modality. The Anthropic Messages endpoint accepts the same key via Authorization: Bearer.

Manage API keys
OpenAI-compatible Multimodal One key Offline sandbox

Base URL

https://api.allgate.ai/v1

The gateway uses a dedicated API domain (shown below), separate from the console origin. Copy it into your client environment.

12 endpoints 3 streaming dialects
Example response JSON
POST POST /v1/chat/completions
{
  "id": "chatcmpl-01a14b8e3c9d71f2",
  "object": "chat.completion.chunk",
  "model": "deepseek-flash",
  "choices": [
    { "index": 0, "delta": { "content": "Allgate is…" } }
  ],
  "usage": { "prompt_tokens": 22, "completion_tokens": 509 }
}
Illustrative response · no request submitted

Authentication

Authentication & base URL

Every compatible-gateway request is authenticated with an API key. Keys are bound to a user and quota, and can be created, rotated or revoked at any time.

API key

Create one on the Keys page. The full secret is shown once on creation or rotation — store it in your secret manager immediately.

Authorization: Bearer sk-allgate-…

Base URL

The common prefix of every compatible endpoint, configured server-side — normally https://api.allgate.ai/v1.

https://api.allgate.ai/v1

Environment variables

Every sample below reads the base URL and API key from environment variables.

Environment variables
env.sh 
export ALLGATE_BASE_URL='https://api.allgate.ai/v1'
export ALLGATE_API_KEY="sk-allgate-…"  # create one under Keys
01

Create an API key

Generate a key on the console Keys page, optionally with a model allowlist, quota and rate limits.

02

Set the environment

Export ALLGATE_BASE_URL and ALLGATE_API_KEY so every sample and SDK picks them up.

03

Send the first request

Use any OpenAI SDK or HTTP client against /chat/completions — start with the sandbox model.

See the chat example →

Drop-in OpenAI SDKs

No new SDK: point base_url at Allgate and use an Allgate key as api_key. The same key also serves /v1/messages and /v1/responses; those requests must use Authorization: Bearer.

Examples use this currently available model. Availability and endpoint compatibility may change; check the catalogue before integrating.

Python · openai SDK
quickstart.py 
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ALLGATE_API_KEY"],
    base_url="https://api.allgate.ai/v1",
)

completion = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Hello, Allgate!"}],
)
print(completion.choices[0].message.content)
Node · openai SDK
quickstart.mjs 
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ALLGATE_API_KEY,
  baseURL: "https://api.allgate.ai/v1",
});

const completion = await client.chat.completions.create({
  model: "deepseek-flash",
  messages: [{ role: "user", content: "Hello, Allgate!" }],
});
console.log(completion.choices[0].message.content);

Samples use the official openai package. The official Anthropic SDK sends x-api-key by default, which this gateway does not accept; call /v1/messages with an HTTP client or a custom Authorization header.

Security practices

  • Keys are stored hashed — the plaintext cannot be recovered. Save it right after creation.
  • Use separate keys per environment and scope them with RPM/TPM limits and model allowlists.
  • Never hardcode a key in frontend code — browser traffic should go through your own backend.

Endpoint reference

Every capability, one protocol

Compatible endpoints grouped by capability. Request/response samples follow the language switch above; paths and fields follow docs/API.md.

Chat Completions

The OpenAI-compatible chat endpoint and the default recommendation. Multimodal input, tool calls, reasoning fields and SSE streaming.

POST
/v1/chat/completions

Create a chat completion (JSON or SSE stream)

Request
curl.sh 
curl -s "$ALLGATE_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ALLGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Hello, Allgate"}
    ],
    "temperature": 0.7
  }'
Response
response.json 
{
  "id": "chatcmpl-01a14b8e3c9d71f2a1b2c3d4e5f6",
  "object": "chat.completion",
  "created": 1792269000,
  "model": "deepseek-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Allgate is a unified model gateway…"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 22,
    "completion_tokens": 509,
    "total_tokens": 531
  }
}

Notes

  • Most OpenAI clients only need a new base_url and api_key — no code changes.
  • model is a public Allgate model name; the channel’s model mapping is applied transparently upstream.

Responses

The OpenAI Responses API. OpenAI-native channels pass through untouched; every other channel is translated to Chat Completions and back.

POST
/v1/responses

Create a response (JSON or Responses SSE)

Request
curl.sh 
curl -s "$ALLGATE_BASE_URL/responses" \
  -H "Authorization: Bearer $ALLGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash",
    "input": "Explain Allgate in one sentence, then give me three key points."
  }'
Response
response.json 
{
  "id": "resp_01a14b8e44aa71c2b4d7f0e1a2b3c4d5",
  "object": "response",
  "created_at": 1792269000,
  "status": "completed",
  "model": "deepseek-flash",
  "output": [
    {
      "type": "message",
      "id": "msg_01a14b8e44ab72d3c5e8f1a2b3c4d5e6",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Allgate is one gateway for every model capability…",
          "annotations": []
        }
      ]
    }
  ],
  "output_text": "Allgate is one gateway for every model capability…",
  "usage": {
    "input_tokens": 22,
    "output_tokens": 509,
    "total_tokens": 531
  }
}

Notes

  • Responses include output / output_text / usage; streaming emits response.created … response.completed.
  • tools, instructions and max_output_tokens behave like the official Responses API.

Messages (Anthropic dialect)

The Anthropic Messages protocol. Anthropic channels pass through almost verbatim; any chat-capable channel also works via automatic translation.

POST
/v1/messages

Create a message (JSON or Anthropic SSE)

Request
curl.sh 
curl -s "$ALLGATE_BASE_URL/messages" \
  -H "Authorization: Bearer $ALLGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash",
    "max_tokens": 512,
    "system": "You are Allgate, a concise assistant.",
    "messages": [
      {"role": "user", "content": "Explain Allgate in one sentence."}
    ]
  }'
Response
response.json 
{
  "id": "msg_01a14b8e52bb73e4d6f901a2b3c4d5e6",
  "type": "message",
  "role": "assistant",
  "model": "deepseek-flash",
  "content": [
    { "type": "text", "text": "Allgate is one OpenAI-compatible gateway in front of every model vendor." }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": { "input_tokens": 22, "output_tokens": 24 }
}

Notes

  • Native channels keep Anthropic-only fields such as cache_control, thinking and metadata.
  • Translated channels map system, multimodal content parts and tool calls onto Chat Completions.

Embeddings

Turn text into vectors for search, clustering and RAG. OpenAI-shaped embeddings request and response.

POST
/v1/embeddings

Create text embeddings (dimensions and base64 supported)

Request
curl.sh 
curl -s "$ALLGATE_BASE_URL/embeddings" \
  -H "Authorization: Bearer $ALLGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_EMBEDDING_MODEL",
    "input": ["Allgate gateway", "openai compatible gateway"],
    "dimensions": 256
  }'
Response
response.json 
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0123, -0.0456, 0.0789]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [0.0234, -0.0567, 0.0891]
    }
  ],
  "model": "YOUR_EMBEDDING_MODEL",
  "usage": { "prompt_tokens": 6, "total_tokens": 6 }
}

Notes

  • input accepts a single string or an array of strings; dimensions trims the vector when the model supports it.
  • The sandbox model returns deterministic vectors, ideal for offline experiments.

Images

Text-to-image generation. The sandbox channel returns real generated SVG artwork; image vendors are proxied directly.

POST
/v1/images/generations

Generate images (url or b64_json)

Request
curl.sh 
curl -s "$ALLGATE_BASE_URL/images/generations" \
  -H "Authorization: Bearer $ALLGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "Light beams and spectrum at sunset, minimalist poster",
    "n": 1,
    "size": "1024x1024"
  }'
Response
response.json 
{
  "created": 1792269000,
  "data": [
    {
      "url": "/media/sandbox-image-01a14b8e5f1c73b2c4d5e6f7a8b9.svg",
      "revised_prompt": "Light beams and spectrum at sunset, minimalist poster",
      "media_path": "sandbox-image-01a14b8e5f1c73b2c4d5e6f7a8b9.svg"
    }
  ],
  "model": "gemini-3.1-flash-image",
  "allgate_sandbox": true
}

Notes

  • n controls the number of images (up to 4 in the sandbox); size accepts the usual aspect ratios.
  • Sandbox artifacts are written to the media directory and served at /media/<file>; responses carry an allgate_sandbox marker.

Audio

Text-to-speech and speech-to-text. Speech returns binary audio; transcription accepts a multipart/form-data upload.

POST
/v1/audio/speech

Text-to-speech (binary audio response)

POST
/v1/audio/transcriptions

Speech-to-text (multipart upload → JSON/text/SRT/VTT)

Text to speech
curl.sh 
# text-to-speech: the response body is audio, not JSON
curl -s "$ALLGATE_BASE_URL/audio/speech" \
  -H "Authorization: Bearer $ALLGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_SPEECH_MODEL","input":"Hello, Allgate","voice":"nova"}' \
  -o speech.wav
Transcription
curl.sh 
# speech-to-text: multipart/form-data upload
curl -s "$ALLGATE_BASE_URL/audio/transcriptions" \
  -H "Authorization: Bearer $ALLGATE_API_KEY" \
  -F model='YOUR_TRANSCRIPTION_MODEL' \
  -F response_format=json \
  -F file=@sample.wav
Binary response
response.txt 
HTTP/1.1 200 OK
content-type: audio/wav
x-allgate-request-id: req_01a14b8e6a2d75c4d6e7f8a9b0c1d2e3
x-allgate-model: YOUR_SPEECH_MODEL

<binary audio bytes — RIFF header, 24 kHz mono WAV for the sandbox>
Transcription response
response.json 
{
  "text": "[Allgate Sandbox] Welcome to the Allgate Sandbox demo transcription. …",
  "task": "transcribe",
  "language": "en",
  "duration": 1.25,
  "segments": [
    { "id": 0, "start": 0.0, "end": 1.25, "text": "…" }
  ],
  "allgate_sandbox": true
}

Notes

  • The speech content-type comes from the vendor (audio/mpeg, audio/wav, …); the sandbox always returns WAV.
  • Transcription supports response_format=json|text|srt|vtt; non-JSON responses pass through unchanged.

Video (async)

Async

Video generation is asynchronous: create a task, then poll until succeeded / failed. Synchronous and asynchronous vendors share the same task semantics.

POST
/v1/videos/generations

Create a video generation task (202 Accepted)

GET
/v1/videos/generations/{id}

Poll task status and result

Request
curl.sh 
# 1) enqueue a task — 202 Accepted
curl -s "$ALLGATE_BASE_URL/videos/generations" \
  -H "Authorization: Bearer $ALLGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.5-720p","prompt":"A gate of light floating above the sea","duration":2}'

# 2) poll every ~2s until status is succeeded / failed
curl -s "$ALLGATE_BASE_URL/videos/generations/$TASK_ID" \
  -H "Authorization: Bearer $ALLGATE_API_KEY"
Create response · 202
response.txt 
HTTP/1.1 202 Accepted

{
  "id": "01a14b8e7b3c74d5e6f7a8b9c0d1e2f3",
  "object": "video.generation",
  "status": "queued",
  "model": "seedance-2.5-720p",
  "created": 1792269000,
  "progress": 0,
  "prompt": "A gate of light floating above the sea"
}
Poll response · 200
response.json 
{
  "id": "01a14b8e7b3c74d5e6f7a8b9c0d1e2f3",
  "object": "video.generation",
  "status": "succeeded",
  "model": "seedance-2.5-720p",
  "created": 1792269000,
  "completed": 1792269005,
  "progress": 100,
  "prompt": "A gate of light floating above the sea",
  "result": {
    "url": "/media/sandbox-video-01a14b8e7c4d75e6f7a8b9c0d1e2f3a4.svg",
    "duration_secs": 2
  }
}

Notes

  • Poll roughly every 1–2 seconds; progress advances from 0 to 100.
  • Sandbox tasks finish in about 4–5 seconds and point at an animated SVG under /media/; vendor channels return their hosted URL.

Rerank

Re-order candidate documents by relevance to a query, with Cohere / Jina-style request and response shapes.

POST
/v1/rerank

Rerank documents (returns relevance scores)

Request
curl.sh 
curl -s "$ALLGATE_BASE_URL/rerank" \
  -H "Authorization: Bearer $ALLGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_RERANK_MODEL",
    "query": "Allgate model gateway",
    "documents": [
      "The weather is nice today",
      "Allgate is a unified model gateway",
      "A cat is sitting on a mat"
    ],
    "top_n": 2
  }'
Response
response.json 
{
  "id": "rerank-01a14b8e8c5d76f7a8b9c0d1e2f3a4b5",
  "object": "rerank",
  "model": "YOUR_RERANK_MODEL",
  "results": [
    { "index": 1, "relevance_score": 0.792937 },
    { "index": 2, "relevance_score": 0.412108 }
  ],
  "usage": { "prompt_tokens": 31, "total_tokens": 31 }
}

Notes

  • documents accepts strings or { text } objects; top_n limits the result count.

Models

List the public models available to this key and retrieve a single entry by model name.

GET
/v1/models

List available models

GET
/v1/models/{model}

Retrieve a single model

List models
curl.sh 
curl -s "$ALLGATE_BASE_URL/models" \
  -H "Authorization: Bearer $ALLGATE_API_KEY"
Retrieve model
curl.sh 
curl -s "$ALLGATE_BASE_URL/models/deepseek-flash" \
  -H "Authorization: Bearer $ALLGATE_API_KEY"
List response
response.json 
{
  "object": "list",
  "data": [
    { "id": "deepseek-flash", "object": "model", "created": 1704067200, "owned_by": "Allgate" },
    { "id": "deepseek-flash", "object": "model", "created": 1704067200, "owned_by": "Anthropic" },
    { "id": "deepseek-flash", "object": "model", "created": 1704067200, "owned_by": "OpenAI" }
  ]
}
Retrieve response
response.json 
{
  "id": "deepseek-flash",
  "object": "model",
  "created": 1704067200,
  "owned_by": "Allgate"
}

Notes

  • The payload matches OpenAI /v1/models and only includes models served by at least one healthy channel.
  • The key’s model allowlist applies to both this list and actual routing.

Streaming

Server-sent events

Set stream to true and the response becomes an incremental text/event-stream. Allgate accounts token usage and time-to-first-token when the stream ends.

01

Set "stream": true and send Accept: text/event-stream.

02

Each data: line is one incremental event; event names depend on the client dialect (three dialects below).

03

When the stream ends the connection closes; [DONE], message_stop and response.completed are the per-dialect terminators.

Three client dialects

OpenAI SSE

The default stream format for OpenAI-compatible endpoints; every event is a chat.completion.chunk.

  1. 1 chat.completion.chunk (delta.content)
  2. 2 chat.completion.chunk (finish_reason)
  3. 3 chat.completion.chunk (usage, optional)
  4. 4 [DONE]
Terminates with data: [DONE]
Open a stream
stream.sh 
curl -N "$ALLGATE_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ALLGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "deepseek-flash",
    "stream": true,
    "stream_options": {"include_usage": true},
    "messages": [{"role": "user", "content": "Explain Allgate step by step"}]
  }'

Usage, TTFT and aborts

  • Billing uses the actual tokens when the stream ends; when an upstream omits usage the gateway falls back to a conservative estimate.
  • x-allgate-request-id, x-allgate-model and x-allgate-channel are returned as headers; x-allgate-cost-micros is only available on unary responses.
  • Client disconnects cancel the upstream request and finalize usage exactly once.

Client parsing example

Parse SSE incrementally, skip blank lines and comments, and stop at the terminator.

stream.py 
import json
import os
import httpx

base = os.environ["ALLGATE_BASE_URL"]
headers = {"Authorization": "Bearer " + os.environ["ALLGATE_API_KEY"]}

with httpx.stream(
    "POST",
    base + "/chat/completions",
    headers=headers,
    json={
        "model": "deepseek-flash",
        "stream": True,
        "messages": [{"role": "user", "content": "Explain Allgate step by step"}],
    },
    timeout=None,
) as response:
    response.raise_for_status()
    for line in response.iter_lines():
        if not line.startswith("data:"):
            continue
        payload = line[5:].strip()
        if payload == "[DONE]":
            break
        choices = json.loads(payload).get("choices", [])
        if choices:
            print(choices[0].get("delta", {}).get("content", ""), end="", flush=True)

Errors

Error envelopes and codes

OpenAI-compatible endpoints return the OpenAI error envelope; /v1/messages returns the Anthropic envelope. Messages are sanitized — keys and headers are never included.

OpenAI endpoints · OpenAI envelope
error.openai.json 
{
  "error": {
    "message": "The model `gpt-4x` does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_not_found"
  }
}
Messages endpoint · Anthropic envelope
error.anthropic.json 
{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The model `gpt-4x` does not exist or you do not have access to it."
  }
}
StatustypecodeMeaning
400invalid_request_errorinvalid_json / invalid_modelMalformed request, parameters or JSON.
401authentication_errorinvalid_api_keyAPI key missing, invalid or revoked.
402insufficient_quotainsufficient_balance / quota_exceededInsufficient balance, or this key reached its spend quota.
403permission_erroraccount_disabledAccount or key disabled — access denied.
404invalid_request_errormodel_not_foundUnknown, inactive or not in the key’s model allowlist.
429rate_limit_errorrate_limit_exceededRPM / TPM limit hit — retry after Retry-After.
500server_errorinternal_errorInternal gateway error; it has been logged.
502upstream_errorupstream_error / connection_errorUpstream provider unreachable, timed out or errored; nothing is billed.
504timeout_errortimeoutUpstream did not answer within the timeout; safe to retry.

/v1/messages also returns the Anthropic envelope for authentication and rate-limit errors: {"type":"error","error":{"type":"authentication_error","message":"…"}}.

Rate limits

Rate limits and headers

Limits are per API key (RPM and TPM windows). Rejected requests return 429 with retry guidance in the response headers.

Headers

HeaderMeaning
X-RateLimit-Limit-RequestsRequests per minute allowed for this key.
X-RateLimit-Remaining-RequestsRemaining requests in the current window.
X-RateLimit-Limit-TokensTokens per minute allowed for this key.
X-RateLimit-Remaining-TokensRemaining tokens in the current window.
Retry-AfterSeconds until the request may be retried.
429 example
rate-limit.http 
HTTP/1.1 429 Too Many Requests
Retry-After: 2
X-RateLimit-Limit-Requests: 2
X-RateLimit-Remaining-Requests: 0
X-RateLimit-Limit-Tokens: 240000
X-RateLimit-Remaining-Tokens: 239812

{
  "error": {
    "message": "Rate limit reached for requests per minute — retry in 2s.",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}

OpenAI endpoints return the rate_limit_error envelope; /v1/messages returns the Anthropic rate_limit_error envelope.

Sandbox

Sandbox quick start: no upstream key required

The Allgate Sandbox is a fully offline demo channel covering chat, embeddings, images, video, audio and rerank. Every result is labelled as Allgate Sandbox output.

Offline demo channel

The sandbox exercises the whole pipeline with no upstream credentials: streaming chat, deterministic embeddings, SVG artwork, WAV speech, async video tasks and relevance scores. Generated media lives in the media directory and is served at /media/<file>.

Sandbox model catalogue

Sandbox
ModelCapabilityOutput
allgate-sandbox-chatChat / streaming MarkdownBilingual Markdown with usage and TTFT
allgate-sandbox-embeddingDeterministic text vectorsFloat arrays or base64 vectors
allgate-sandbox-imageText to imageSVG artwork file /media/…
allgate-sandbox-videoAsync text to videoAnimated SVG task result /media/…
allgate-sandbox-ttsText to speech / transcriptionPlayable WAV (speech) / demo transcript
allgate-sandbox-rerankRelevance rerankRanked relevance scores

Artifacts and access

  • Image, speech and video artifacts are stored in config.media_dir and served from the console origin at /media/<file>.
  • The url in media responses is relative; prefix it with the current origin when an absolute URL is required.
  • Every sandbox response carries an allgate_sandbox marker so the UI can label demo data.
Generate images
image.sh 
curl -s "$ALLGATE_BASE_URL/images/generations" \
  -H "Authorization: Bearer $ALLGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"allgate-sandbox-image","prompt":"Spectrum-colored city skyline","n":2}'
Create a video task
video.sh 
curl -s "$ALLGATE_BASE_URL/videos/generations" \
  -H "Authorization: Bearer $ALLGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"allgate-sandbox-video","prompt":"Coastline light time-lapse","duration":2}'

# then poll GET /v1/videos/generations/{id} until status=succeeded

Before you choose a model.

How do I connect to the Allgate API?
Create an account and API key, set your application base URL to https://api.allgate.ai/v1, and choose a currently available model ID from the public catalogue. Send the key as a Bearer token. Keep API keys on your server, outside browser code.
Does a documented endpoint guarantee model availability?
The API reference describes request formats. The live catalogue lists models and their current routing availability. An endpoint or reference index entry does not mean that every model or capability has an available route.
Where can I check request formats and costs?
The public API reference covers authentication, request shapes, streaming and errors. Model detail pages publish billing units and base rates; your console shows the applicable account price.

Catalogue snapshot: · Public model data · Models and prices · Image and video Studio · API reference