Zaawansowana wielomodalna brama AI obsługująca Google Gemini (2/3)
Zaawansowana wielomodalna brama AI obsługująca Google Gemini (2/3), Anthropic Claude, OpenAI, xAI Grok, Moonshot Kimi K3 i OpenRouter, z automatyczną naprawą JSON opartą na maszynie stanów oraz fallbackiem wydobywania JSON owiniętego w prozę, opcjonalnym…
Żądanie
- x-api-key: <your-api-key>
- Content-Type: application/json
Odpowiedź
{
"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"
}
}Co robi
Zaawansowana wielomodalna brama AI obsługująca Google Gemini (2/3), Anthropic Claude, OpenAI, xAI Grok, Moonshot Kimi K3 i OpenRouter, z automatyczną naprawą JSON opartą na maszynie stanów oraz fallbackiem wydobywania JSON owiniętego w prozę, opcjonalnym templatingiem Mustache dla instructions/prompt i opcjonalnym streamingiem (`options.stream: true` odpowiada jako text/event-stream). Puste completion liczy się jako nieudany kandydat, a domyślny łańcuch przechodzi dalej.
Żądanie
Treść
| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
fileUrls | array<string> | nie | Optional array of remote file URLs to process and inject into final prompt context |
instructions | string | boolean | nie | System instructions / prompt |
maxRetries | integer | nie | |
model | string | nie | 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 | nie | |
↳ max_tokens | integer | nie | |
↳ reasoning | object | nie | 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 | nie | |
↳ stream | boolean | nie | 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 | nie | 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> | nie | |
↳ top_k | number | nie | |
↳ top_p | number | nie | |
prompt | string | array | tak | A single prompt string or an array of chat messages [{"role": "user", "content": "..."}] |
provider | enum | nie | 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 | nie | 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 | nie | 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 | nie | 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. |
Przykładowe żądanie
{
"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": {}
}Odpowiedź
| Pole | Typ | Opis |
|---|---|---|
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. |
Przykładowa odpowiedź
{
"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"
}
}Błędy
Każdy błąd ma tę samą kopertę: status HTTP, kod maszynowy i jedno zdanie.
400 | Treść albo parametr nie przeszły walidacji. Tablica details wskazuje pole. |
401 | Brak klucza, klucz cofnięty albo zły nagłówek. Wyślij x-api-key. |
402 | Portfel nie pokrywa tego wywołania. Doładuj albo poczekaj na miesięczny przydział. |
404 | Zasób nie istnieje albo nie jest Twój. Obie sytuacje odpowiadają identycznie i nic nie kosztują. |
429 | Przekroczony limit na minutę dla Twojego planu. Odczekaj i ponów. |
5xx | Usługa nadrzędna odmówiła albo przekroczyła czas. Wywołanie nie jest rozliczane. |
Kod
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);Koszt i limity
Ta operacja kosztuje od 2 tokenów. Nieudane wywołanie nigdy nie jest rozliczane. Każde konto dostaje 1000 darmowych tokenów miesięcznie; opłacone saldo nie wygasa. 2 tokeny plus zużycie tokenów po stronie modelu, według stawki tego modelu. Blok `usage` w odpowiedzi pokazuje, co dokładnie zostało policzone. Dostępne w planach PRO i Enterprise: ta operacja zużywa własne klucze lub limity castomAPI. Klucz z planu darmowego dostaje 403 i nie jest rozliczany.
Limity żądań na minutę
| Bez klucza | 10 |
| Free | 60 |
| Pro | 300 |
| Enterprise | 1200 |
Pytania
Ile kosztuje Zaawansowana wielomodalna brama AI obsługująca Google Gemini (2/3)?
od 2 tokenów za udane wywołanie, pobierane z portfela po odpowiedzi. Nieudane wywołania są bezpłatne. Każde konto dostaje 1000 darmowych tokenów miesięcznie. 2 tokeny plus zużycie tokenów po stronie modelu, według stawki tego modelu. Blok `usage` w odpowiedzi pokazuje, co dokładnie zostało policzone.
Jak się uwierzytelnić?
Wyślij klucz w nagłówku x-api-key. Jeden klucz obejmuje każdy rozliczany endpoint; niczego nie trzeba włączać osobno.
Czy mogę wysłać nagłówek Authorization: Bearer zamiast klucza?
Nie dla rozliczanego endpointu — te przyjmują wyłącznie nagłówek x-api-key. Tokeny Bearer należą do strony konta: panel i API konta przyjmują sesję JWT, a castomapi-auth wydaje je standardowym uzgodnieniem OAuth2, z grantami authorization code, client credentials i refresh. Opisuje to strona usługi auth.
Jakie są limity?
10 żądań na minutę z jednego IP zupełnie bez klucza, 60 na minutę w planie Free, 300 w Pro, 1200 w Enterprise. Powyżej poziomu bez klucza limit jest na konto, łącznie dla wszystkich endpointów.
OpenAPI: https://app.castomapi.com/docs/json