API Reference

This is the complete list of SpiderGate endpoints. Everything the dashboard, the SDKs, and your agents do goes through these. They're OpenAI-compatible, so an OpenAI client pointed at the base URL works against them directly.

Base URL

https://spideriq.ai/api/gate/v1

All paths below are relative to that base. For the OpenAI SDK, set base_url="https://spideriq.ai/api/gate/v1".

Authentication

Endpoints that read or write your data require a bearer token. The model-listing endpoints and /catalog/leaderboard are public; the rest of the catalog surface needs a token. See Authentication for the two token formats and Model Catalog for that surface.

Authorization: Bearer <client_id>:<api_key>:<api_secret>
Authorization: Bearer spideriq_pat_…

Chat & generation

These require authentication.

POST /chat/completions

Create a chat completion (streaming or non-streaming). The body is the OpenAI chat-completion request; model may be a task alias or a model id.

• Query: include_route_trace (boolean, default false) — inline a per-attempt route trace in the response (non-streaming).

• Response headers: X-SpiderGate-Fallback-From — present (non-streaming) when the served model differs from the alias's first choice.

• Full parameters: Chat Completions. Streaming: Streaming.

POST /images/generations

Generate images with dall-e-3, dall-e-2, or gpt-image-1. Requires an OpenAI key in the vault. See Images, Audio & Embeddings.

POST /audio/speech

Text-to-speech with tts-1, tts-1-hd, or gpt-4o-mini-tts. Returns audio bytes. Voices: alloy, echo, fable, onyx, nova, shimmer. Formats: mp3, opus, aac, flac, wav, pcm.

POST /audio/transcriptions

Speech-to-text with whisper-1, gpt-4o-transcribe, or gpt-4o-mini-transcribe. multipart/form-data; file cap 25 MB.

POST /embeddings

Vector embeddings with text-embedding-3-large, text-embedding-3-small, or text-embedding-ada-002. dimensions up to 3072. Also accepts the SpiderGate aliases agent/embed-small, agent/embed-large and agent/embed, which resolve server side to the matching model. See Images, Audio & Embeddings.

Media (schema-aware)

The two endpoints below are not the OpenAI passthrough above. They route through SpiderGate's adapter-backed pipeline, honour each model's declared parameter schema, and return a stored URL rather than raw bytes. Every media model is paid tier and never pooled, so your brand must hold its own provider key.

GET /media/models

List the media models an agent can call, each with the inputs schema it declares. Read a model's inputs before calling POST /media/generations — parameters the model does not declare are dropped before the provider call.

Parameters

• modality (string, optional) — filter to one modality, e.g. text-to-image, text-to-video, image-to-video, tts, lipsync.

• include_inactive (boolean, optional, default false) — also return coming_soon and disabled models, which are not generatable.

Example

curl "https://spideriq.ai/api/gate/v1/media/models?modality=text-to-video" \
  -H "Authorization: Bearer $CLIENT_ID:$API_KEY:$API_SECRET"

Response

{
  "models": [
    {
      "id": "kie/veo-3-fast",
      "provider": "kie_ai",
      "modality": "text-to-video",
      "modality_group": "video",
      "status": "active",
      "inputs": {
        "prompt":       { "type": "string", "required": true, "control": "textarea" },
        "aspect_ratio": { "type": "enum", "default": "16:9",
                          "enum": ["16:9", "9:16", "1:1"], "control": "segmented" }
      }
    }
  ],
  "total": 1
}

Errors:

POST /media/generations

Generate an image, video, or speech clip from a <provider>/<model> descriptor id. Returns a stored SpiderMedia URL plus a cost breakdown. Video generation is synchronous and can take minutes.

Parameters

• model (string, required, 1–128 chars) — the descriptor id from GET /media/models, e.g. fal/flux-dev, kie/veo-3-fast, openai/tts-1.

• params (object, optional) — the per-model tunables, validated against that model's declared inputs. Extra top-level fields are folded into params, so {"model": …, "seed": 7} and {"model": …, "params": {"seed": 7}} are equivalent; an explicit params entry wins on a clash.

• prompt (string, optional) — a saved-prompt reference, either prompt:<public_id> or prompt.<slug>. The server expands the stored prompt text, model and settings; anything you pass explicitly overrides it.

• project_id (string, optional) — required only to resolve a prompt.<slug> reference.

Example

curl -X POST "https://spideriq.ai/api/gate/v1/media/generations" \
  -H "Authorization: Bearer $CLIENT_ID:$API_KEY:$API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kie/veo-3-fast",
    "params": {
      "prompt": "a slow pan across an empty server room",
      "aspect_ratio": "16:9"
    }
  }'

Response

{
  "id": "media-6ff96279d9894632b730aa92",
  "model": "kie/veo-3-fast",
  "provider": "kie_ai",
  "request_kind": "video",
  "cost_usd": 0,
  "billed_usd": 0,
  "est_cost": {
    "provider_cost_usd": 0,
    "billed_usd": 0,
    "markup_pct": 0,
    "key_ownership": "byok",
    "basis": "byok_monthly_package",
    "currency": "USD"
  },
  "stored": true,
  "data": [ { "url": "https://media.spideriq.ai/client-…/gate-media/….png" } ],
  "ignored_params": [],
  "warnings": []
}

ignored_params names any parameter the model did not declare, so a silently dropped field is still visible to you. billed_usd is 0 when the generation ran on your own paid key.

Errors:

Note that a long video generation can outlive an intermediate proxy timeout even though the run completes and is billed. If a call returns a gateway timeout, check GET /media/models usage or your Traces before resending — the asset may already exist.

Catalog (public, no auth)

GET /models

List the model catalog in OpenAI list format, each entry with a spidergate_info block. Query params: provider, free_only, configured_only, search, capability, sort_by, limit (1–2000), offset. See Models.

GET /models/{model_id}

Return one model, or 404 model_not_found if unknown.

GET /aliases

List every task alias with its ranked model fallback chain and its 30-day usage. Public, no auth. This is the authoritative list: the 32 aliases and 91 chain slots below move as providers change, so read them here rather than hardcoding them. See Task Aliases.

Parameters: none.

Example

curl "https://spideriq.ai/api/gate/v1/aliases"

Response — 200, an OpenAI-style list. data holds 32 entries; models is the fallback chain in priority order, index 0 first.

{
  "object": "list",
  "data": [
    {
      "id": "spideriq/lead-analysis",
      "description": "B2B lead analysis and scoring",
      "use_case": "Company vitals, pain points, CHAMP scoring, team extraction",
      "models": [
        { "provider": "cerebras", "model": "gpt-oss-120b", "spidergate_id": null },
        { "provider": "groq", "model": "llama-3.3-70b-versatile", "spidergate_id": "llama-3.3-70b-groq" },
        { "provider": "minimax", "model": "MiniMax-M2.5", "spidergate_id": "minimax-m2.5-qwen" }
      ],
      "usage": { "requests_30d": 43863, "tokens_30d": 301092346, "cost_30d": 203.16232776 }
    }
  ]
}

Errors:

::table
Status | Code | When and what to do
`503` | `service_unavailable` | The routing engine is still starting up. Retry after a short backoff; no request body change is needed.

A spidergate_id of null means the model is served under its provider-native id rather than a SpiderGate catalog id. Read models[0] to know which model an alias currently leads with, and the array length to know how deep its chain runs.

GET /providers

List the upstream providers SpiderGate can route to, with model counts and key status.

GET /health

Process liveness check.

curl "https://spideriq.ai/api/gate/v1/health"
# {"status":"healthy","service":"spidergate","version":"…"}

Endpoint summary

Authenticated:

• POST /chat/completions — chat completion, streaming and non-streaming

• POST /media/generations — schema-aware image, video and speech generation

• GET /media/models — media models and the parameter schema each one declares

• POST /images/generations — image generation, OpenAI passthrough

• POST /audio/speech — text-to-speech, returns audio bytes

• POST /audio/transcriptions — transcription, multipart upload

• POST /embeddings — vector embeddings

Public, no token:

• GET /models — list models

• GET /models/{model_id} — get one model

• GET /aliases — list task aliases and their fallback chains

• GET /providers — list providers

• GET /health — liveness check

Observability

Every response carries enough to reconcile what your code saw with what the Traces view shows. All of it is on the normal bearer-authenticated surface; none of it needs a second call.

Response headers

• x-trace-id — present on every response. The trace identifier for this request. Log it, then paste it into the Traces search box to find this exact request.

• X-SpiderGate-Fallback-From — present on non-streaming responses only when the served model differs from the alias's first choice. Its value is the model the alias would have used, so its presence means a fallback occurred.

The response body's model field is always the model that actually served the request, which is not necessarily the model you sent. Compare the two to detect a silent fallback.

curl -sD - -X POST "https://spideriq.ai/api/gate/v1/chat/completions" \
  -H "Authorization: Bearer $CLIENT_ID:$API_KEY:$API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"model":"spideriq/fast","messages":[{"role":"user","content":"hello"}]}' \
  -o /dev/null | grep -i 'x-trace-id\|fallback-from'
# x-trace-id: 441c7118-77b3-4e33-a369-d9edcff2123d

POST /chat/completions?include_route_trace=true

Add ?include_route_trace=true to POST /chat/completions to inline the per-attempt dispatch detail in the response body (non-streaming). Use it when you need to know why a request took the path it did.

curl -s -X POST "https://spideriq.ai/api/gate/v1/chat/completions?include_route_trace=true" \
  -H "Authorization: Bearer $CLIENT_ID:$API_KEY:$API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"model":"spideriq/fast","messages":[{"role":"user","content":"hello"}]}'

The response gains a route_trace array, one entry per dispatch attempt:

{
  "id": "chatcmpl-5e780d89033f433ea999879e",
  "model": "nvidia_nim/meta/llama-3.1-8b-instruct",
  "route_trace": [
    { "attempt": 0, "path": "router", "model": "spideriq/fast", "outcome": "success", "latency_ms": 390 }
  ]
}

Each entry carries:

• attempt (integer) — zero-based attempt index. More than one entry means the first choice did not serve.

• path (string) — which dispatch path handled the attempt, for example router.

• model (string) — the model or alias tried on this attempt.

• outcome (string) — success, or the failure classification for that attempt.

• latency_ms (integer) — wall-clock time for the attempt.

Errors: include_route_trace is advisory and never changes the status code: an unrecognised value is ignored and the request proceeds without a trace. Authentication, budget, model-permission and rate-limit failures return their usual 401 / 402 / 403 / 429 before any dispatch happens, so no route_trace is present on those responses. See Errors.

Reading traces back

There is no bearer-authenticated endpoint for querying stored traces. Trace history is a dashboard surface, described in Traces; the x-trace-id header above is how you correlate a request your code made with its row there.

Dashboard endpoints

The dashboard surfaces (agents, usage, traces, vault) are served by brand-scoped endpoints under /api/v1/brands/{brand_id}/gate/* and are authenticated by your dashboard session rather than a gateway bearer token. They power the dashboard and are not part of the OpenAI-compatible surface; use the dashboard UI to drive them.

Next steps

1. Authenticate your calls — Authentication.

2. Handle failures correctly — Errors.

3. Stay within limits — Rate Limits & Budgets.