Advanced Multimodal AI Gateway supporting…

What it does

Advanced Multimodal AI Gateway supporting Google Gemini (2/3), Anthropic Claude, OpenAI, xAI Grok, Moonshot Kimi K3, and OpenRouter, with automated state-machine JSON repairing plus a prose-wrapped-JSON extraction fallback, optional Mustache templating for instructions/prompt, and optional streaming (`options.stream: true` answers as text/event-stream). An empty completion counts as a failed candidate and the house chain walks on.base + the upstream token usage at the answering model's rate, set per model by the administrator; the response's `usage` block shows what was counted. A call made with your own `providerApiKey` costs the 2-token base only.)

Request

Body

Field	Type	Required	Description
`fileUrls`	array<string>	no	Optional array of remote file URLs to process and inject into final prompt context
`instructions`	string \| boolean	no	System instructions / prompt
`maxRetries`	integer	no
`model`	string	no	Model identifier (e.g., gemini-3.1-pro, claude-3-5-sonnet-20241022, gpt-4o, grok-2, or an OpenRouter slug like "openai/gpt-4o" or "stealth/ox-alpha"). Omit together with `provider` to use this server's configured house models.
`options`	object	no
`↳ max_tokens`	integer	no
`↳ reasoning`	object	no	Reasoning control, forwarded verbatim. OpenAI: selects the Responses API (`{ effort }`). OpenRouter: its unified `reasoning` parameter (`{ effort: "low" \| "medium" \| "high" }` or `{ max_tokens }`) -- note some models refuse `{ enabled: false }` outright, so ask for a low effort rather than none. Ignored by every other provider.
`↳ response_format`	object	no
`↳ stream`	boolean	no	Answer as a text/event-stream instead of one JSON body. Events: `status` ({stage:"thinking"}, once, when a reasoning model starts thinking), `delta` ({text}) for every piece of the answer as the model produces it, then `done` carrying exactly the JSON body the non-streamed call would have returned (status, provider, model, text, object, rawResponse...), or `error` ({message}) if the answer failed after it had started. A failure before anything was produced is answered with the ordinary JSON 502/504, so check the content-type. OpenAI-compatible providers stream for real; Gemini, Anthropic and the OpenAI Responses API deliver their whole answer as a single `delta`. Same cost as a buffered call.
`↳ temperature`	number	no	Ignored for provider "kimi" -- Kimi K3 rejects any value other than 1, so it is always sent as 1 regardless of this field. Also ignored for Anthropic models from Claude Opus 4.7 onward (incl. Opus 5, Sonnet 5, Fable 5), which reject temperature/top_p/top_k outright -- they are omitted so the call succeeds on the provider default.
`↳ tools`	array<any>	no
`↳ top_k`	number	no
`↳ top_p`	number	no
`prompt`	string \| array	yes	A single prompt string or an array of chat messages [{"role": "user", "content": "..."}]
`provider`	enum	no	AI Provider identifier. Omit together with `model` to use this server's configured house models. One of: openai, grok, gemini2, gemini3l, gemini3h, anthropic, claude, kimi….
`providerApiKey`	string	no	Optional provider API Key. If omitted, the key comes from the admin dashboard's stored key for the provider, then from the server environment variable.
`skipCandidates`	integer	no	House chain only (no effect when provider/model is given): start the fallback walk this many candidates in, rather than at rank 1. For a caller that already knows its request timed out against the earlier candidates last time -- the fastest model in most chains is also the one with the least headroom for a long completion, so a caller retrying the SAME request is better served skipping straight to whatever is next, not paying for the same timeout twice. Clamped to the chain's own length: a value that would skip every candidate skips none instead, since an empty chain is not a request that can be answered. The chain is the enabled AND priced house rows, in the admin's order -- an unpriced row holds no rank.
`templateData`	object	no	Optional Mustache view data. When non-empty, instructions and every prompt message are rendered as Mustache templates against it before the request is sent -- supports {{var > 5}}/{{var1 + var2}}-style comparison and arithmetic tags on top of plain Mustache. Left empty (the default), instructions/prompt are sent through untouched, so a literal "{{like this}}" in a normal prompt is never mangled.

Example request

{
  "fileUrls": [],
  "instructions": "<instructions>",
  "maxRetries": 2,
  "model": "gpt-4o",
  "options": {},
  "prompt": "Write a one-line welcome for a developer.",
  "provider": "openai",
  "providerApiKey": "<your-api-key>",
  "skipCandidates": 0,
  "templateData": {}
}

Response

Field	Type	Description
`executionTimeMs`	integer
`model`	string
`object`	object \| array
`provider`	string
`rawResponse`	object
`status`	string
`success`	boolean
`text`	string
`tokensDeducted`	integer
`usage`	object
`↳ billedUpstream`	enum	One of: caller, castomapi.
`↳ inputTokens`	integer
`↳ outputTokens`	integer
`↳ source`	enum	One of: reported, estimated.

Example response

{
  "executionTimeMs": 31,
  "model": "gpt-4o",
  "object": {},
  "provider": "castomapi",
  "rawResponse": {},
  "status": "success",
  "success": true,
  "text": "Hello from castomAPI.",
  "tokensDeducted": 2,
  "usage": {
    "billedUpstream": "caller",
    "inputTokens": 19,
    "outputTokens": 34,
    "source": "reported"
  }
}

Errors

Every error answers with the same envelope: an HTTP status, a machine code and a sentence.

`400`	The body or a parameter failed validation. The details array names the field.
`401`	No key, a revoked key or a wrong header. Send x-api-key.
`402`	The wallet cannot cover this call. Top up or wait for the monthly grant.
`404`	The resource does not exist, or it is not yours. Both answer identically and cost nothing.
`429`	Over the per-minute quota of your tier. Back off and retry.
`5xx`	Upstream refused or timed out. The call is not billed.

Code

curl -X POST 'https://app.castomapi.com/v1/proxy/llm' \
  -H 'x-api-key: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{"fileUrls": [], "instructions": "<instructions>", "maxRetries": 2, "model": "gpt-4o", "options": {}, "prompt": "Write a one-line welcome for a developer.", "provider": "openai", "providerApiKey": "<your-api-key>", "skipCandidates": 0, "templateData": {}}'

const res = await fetch('https://app.castomapi.com/v1/proxy/llm', {
  method: 'POST',
  headers: { 'x-api-key': '<your-api-key>', 'Content-Type': 'application/json' },
  body: JSON.stringify({"fileUrls": [], "instructions": "<instructions>", "maxRetries": 2, "model": "gpt-4o", "options": {}, "prompt": "Write a one-line welcome for a developer.", "provider": "openai", "providerApiKey": "<your-api-key>", "skipCandidates": 0, "templateData": {}})
});
const data = await res.json();
console.log(data);

import { request } from 'node:https';

// Node 18+ has fetch built in
const res = await fetch('https://app.castomapi.com/v1/proxy/llm', {
  method: 'POST',
  headers: { 'x-api-key': '<your-api-key>', 'Content-Type': 'application/json' },
  body: JSON.stringify({"fileUrls": [], "instructions": "<instructions>", "maxRetries": 2, "model": "gpt-4o", "options": {}, "prompt": "Write a one-line welcome for a developer.", "provider": "openai", "providerApiKey": "<your-api-key>", "skipCandidates": 0, "templateData": {}})
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    'https://app.castomapi.com/v1/proxy/llm',
    headers={'x-api-key': '<your-api-key>'},
    json={"fileUrls": [], "instructions": "<instructions>", "maxRetries": 2, "model": "gpt-4o", "options": {}, "prompt": "Write a one-line welcome for a developer.", "provider": "openai", "providerApiKey": "<your-api-key>", "skipCandidates": 0, "templateData": {}},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://app.castomapi.com/v1/proxy/llm');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['x-api-key: <your-api-key>', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['fileUrls' => [], 'instructions' => '<instructions>', 'maxRetries' => 2, 'model' => 'gpt-4o', 'options' => [], 'prompt' => 'Write a one-line welcome for a developer.', 'provider' => 'openai', 'providerApiKey' => '<your-api-key>', 'skipCandidates' => 0, 'templateData' => []]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);

Cost and limits

This operation costs from 2 tokens. A call that fails is never billed. Every account gets 1000 free tokens a month; paid balances never expire. 2 tokens, plus the upstream model's own token usage at that model's rate. The response's `usage` block shows exactly what was counted. Available on the PRO and Enterprise plans: this operation spends castomAPI's own keys or quota. A key on the free plan is refused with 403 and is not billed.

Rate limits per minute

No key	10
Free	60
Pro	300
Enterprise	1200

Docs → Pricing

Questions

What does Advanced Multimodal AI Gateway supporting Google Gemini (2/3) cost?

from 2 tokens per successful call, debited from your wallet after the response. Failed calls are free. Every account receives 1000 free tokens a month. 2 tokens, plus the upstream model's own token usage at that model's rate. The response's `usage` block shows exactly what was counted.

How do I authenticate?

Send your key in the x-api-key header. One key covers every metered endpoint; there is nothing to enable per endpoint.

Can I send an Authorization: Bearer token instead?

Not for a metered endpoint — those take the x-api-key header and nothing else. Bearer tokens belong to the account side: the dashboard and account APIs accept a JWT session, and castomapi-auth issues those through a standard OAuth2 handshake, with authorization code, client credentials and refresh grants. The auth service page covers it.

What are the limits?

10 requests a minute per IP with no key at all, 60 a minute on the free tier, 300 on Pro, 1200 on Enterprise. Above the no-key tier the quota is per account, across every endpoint.

OpenAPI: https://app.castomapi.com/docs/json

Request

Response

What it does

Request

Body

Example request

Response

Example response

Errors

Code

Cost and limits

Rate limits per minute

Questions

More in Proxy

Where it fits