ORIX Astra — Provider matrix
State of the AstraProviders module on 2026-11-21. Every fact below was either read in the provider's documentation that
day or observed on the provider's live API that day (marked live). Model metadata rules are in
Packages/AstraProviders/Sources/CuratedCatalog.swift; background research is in docs/RESEARCH.md.
All adapters share the same contract: raw URLRequest through the injected HTTPTransport; one .messageStarted first and
one .messageCompleted(reason) last; failures are thrown as a typed AstraError (before any event for an HTTP failure, so a
retry is safe); Retry-After honoured; keys read at request time and scrubbed from every error; cancelling the consumer
cancels the HTTP stream; HTTP status, request id, time to headers and retry count reported to the DiagnosticsSink for
generation requests.
Summary
| OpenAI | Anthropic | Google Gemini | xAI | OpenRouter | Custom endpoint | |
|---|---|---|---|---|---|---|
| Type | OpenAIProvider |
AnthropicProvider |
GeminiProvider |
XAIProvider |
OpenRouterProvider |
OpenAICompatibleProvider |
| API | Responses | Messages | generateContent | Responses | Chat Completions | Chat Completions |
| Generation | POST /v1/responses |
POST /v1/messages |
POST /v1beta/models/{id}:streamGenerateContent?alt=sse |
POST /v1/responses |
POST /api/v1/chat/completions |
POST {base}/chat/completions |
| Models | GET /v1/models |
GET /v1/models?limit=1000 (paged) |
GET /v1beta/models?pageSize=1000 (paged) |
GET /v1/language-models + GET /v1/models |
GET /api/v1/models |
GET {base}/models |
verify() |
models call | models call | models call | models call | GET /api/v1/key (+ /credits) |
models call |
| Auth | Authorization: Bearer |
x-api-key + anthropic-version: 2026-10-21 |
x-goog-api-key (never in the URL) |
Authorization: Bearer |
Authorization: Bearer + HTTP-Referer, X-Title, X-OpenRouter-Title |
Authorization: Bearer if a key is set, plus the profile's extra headers |
| Request id read from | x-request-id |
request-id |
none sent | x-request-id |
x-generation-id |
x-request-id / request-id |
| Metadata source | curated table (docs) or .providerAPI with text only |
curated table + API limits | API limits + curated prices | API (modalities, prices, efforts) | API | API or .user |
| Live test model | gpt-6-luna |
claude-haiku-5-5 |
gemini-3.1-flash-lite |
grok-4.3 |
openai/gpt-6-luna |
first listed model |
OpenAI
- Why Responses: OpenAI recommends it over Chat Completions for text generation, and tool calling on GPT-6.2 requires it.
- Request:
model,stream: true,store: false,inputitems,instructions(system text),tools(flat function tools,strict: false),max_output_tokens,reasoning: {effort, summary: "auto"},temperature/top_ponly where accepted. GPT-6.2 appends top-levelinstructionsafterinput, so forgpt-6.2-*the system text is sent as a leadingdevelopermessage to keep it cacheable. - Input items: user message with
input_image(data URL,detail: "auto") andinput_textparts; assistant text as a message; tool calls asfunction_callitems (no item id); results asfunction_call_output. - Stream events handled:
response.created/in_progress/queued(identity),response.output_text.delta,response.refusal.delta,response.reasoning_summary_part.added,response.reasoning_summary_text.delta,response.output_item.added/.done(function calls),response.function_call_arguments.delta,response.completed,response.incomplete,response.failed,error. Everything else is ignored, includingresponse.reasoning_text.delta: only the summary is ever surfaced. - Stop reasons: completed →
endOfTurn(toolCallswhen a call was emitted,contentFilterafter a refusal); incompletemax_output_tokens→maxTokens,content_filter→contentFilter. - Usage:
input_tokens(already includes cached),input_tokens_details.cached_tokens/.cache_write_tokens,output_tokens,output_tokens_details.reasoning_tokens. - Parameter handling: models in the curated table get only what they accept (reasoning-family models never get sampling
parameters;
gpt-6.2-*never geteffort: "none"). For any other model the fields are sent and, on a 400 that names an unsupported parameter, removed and the request retried (at most 3 adjustments). Live:400 Unsupported parameter: 'temperature' is not supported with this model(param: "temperature") ongpt-6-lunaandgpt-5-nano;'reasoning.effort' is not supportedongpt-4.1-mini. - Errors:
{"error": {"message", "type", "code", "param"}}; the streamerrorevent is flat (code,message). - Not implemented, deliberately:
stopandseed(the Responses API has no such parameters; they are dropped); replay of encrypted reasoning items between turns (the core message model has nowhere to keep them; tool cycles work without, live ongpt-6-lunaandgpt-6.2-sol); server-side conversation state (store,previous_response_id); hosted tools; structured outputs; audio;service_tier;prompt_cache_key. - Sources: https://developers.openai.com/api/docs/guides/text,
/guides/streaming-responses,/guides/function-calling,/guides/reasoning,/guides/latest-model,/api/reference/resources/responses/streaming-events,/api/docs/models,/api/docs/pricing— read 2026-11-21. Wire format confirmed against live captures the same day.
Anthropic
- Headers:
x-api-key,anthropic-version: 2026-10-21,content-type: application/json. - Request:
model,max_tokens(the user's value, else min(model maximum, 16,000); 4,096 for an unknown model),stream: true,systemas one text block,messages,tools(input_schema,eager_input_streaming: true),stop_sequences,thinking,output_config.effort. - Sampling: never sent. API version 2026-10-21 rejects
temperature,top_pandtop_kon every model (live:400 temperature: Extra inputs are not permitted). Staying on2023-06-01to keep temperature for the 4.x models was considered and not done. - Messages: images as base64
imageblocks before the text; assistant turns astext+tool_use; tool results astool_resultblocks in a user turn. Consecutive turns of the same wire role are merged, so parallel results share one user turn and roles always alternate. - Thinking, per model (table in
CuratedCatalog.swift): adaptive withdisplay: "summarized"where summaries are opt-in; "off" maps to{"type": "disabled"}, to{"type": "between_tools"}on Sonnet 5.5, and to effortlowon models that cannot stop thinking (Fable, Opus 5.5); Haiku 4.5 / Sonnet 4.5 / Opus 4.5 use{"type": "enabled", "budget_tokens"}withmax_tokensraised by the budget. A rejectedthinkingoroutput_configis removed and the request retried. - Thinking blocks are never replayed. Earlier turns go back as text and
tool_useonly. The API accepts this inside a tool cycle (live:claude-haiku-5-5,claude-sonnet-5-5,claude-opus-5-5,claude-haiku-4-5, thinking on), and with nothing replayed no signature can be invalidated by the app trimming or editing history. Thinking text is surfaced only as the summary the API returns, as.reasoningSummaryDelta;signature_deltaandredacted_thinkingare ignored. - Prompt caching:
cache_control: {"type": "ephemeral"}on the system block when the estimated tools + system prefix reaches the model's minimum (512 / 1,024 / 2,048 / 4,096 tokens depending on the model). - Stream events handled:
message_start,content_block_start(text,thinking,tool_use),content_block_delta(text_delta,thinking_delta,input_json_delta),content_block_stop,message_delta,message_stop,error;pingand unknown events are ignored. - Usage:
inputTokens=input_tokens+cache_read_input_tokens+cache_creation_input_tokens(Anthropic reports the uncached remainder only); the two cache counts are also reported as subsets;output_tokens_details.thinking_tokens→reasoningTokens.message_deltausage is cumulative and overrides field by field. - Stop reasons:
end_turn/pause_turn→endOfTurn,max_tokens/model_context_window_exceeded→maxTokens,tool_use→toolCalls,stop_sequence→stopSequence,refusal→contentFilter. - Errors:
{"type": "error", "error": {"type", "message"}, "request_id"}; mid-streamerrorevents are mapped by type (overloaded_error→ overloaded,rate_limit_error→ rate limited, …). - Not implemented, deliberately: server-side refusal fallbacks (beta; they would let a different model answer than the
one selected); 1-hour cache TTL and message-level cache breakpoints; documents / PDF input; server tools; structured
outputs; effort levels above
high; batch; compaction. - Sources: https://platform.claude.com/docs/en/build-with-claude/streaming,
/thinking,/effort,/prompt-caching,/api/errors,/api/migration-2026-10-21,/about-claude/pricing, andGET /v1/models— read 2026-11-21.
Google Gemini
- Endpoint: native API,
streamGenerateContent?alt=sse; the key is thex-goog-api-keyheader. - Request:
systemInstruction,contentswithuser/modelroles (consecutive same-role turns merged),inlineDataimages,tools[].functionDeclarations[]withparametersJsonSchema(the olderparametersfield rejectsadditionalProperties, live),generationConfig(maxOutputTokens,temperature,topP,seed,stopSequences,thinkingConfig). - Tool cycle:
functionCallparts in the model turn,functionResponseparts ({"result": …}or{"error": …}) in the next user turn. Gemini 3 and later return call ids, which are used as they are; Gemini 2.5 returns none, so stable ids are synthesised (gemini-call-<responseId>-<n>) and never sent back. - Thought signatures: Gemini 3 / 4 put a
thoughtSignatureon the firstfunctionCallpart of a turn and answer 400 (Function call is missing a thought_signature) when the replay omits it (live). Signatures are kept in memory by call id and echoed verbatim; when none is known (app restarted, history from another model) the documented placeholderskip_thought_signature_validatoris sent (live: accepted bygemini-3.1-flash-lite,gemini-4-hydrogen,gemini-2.5-flash-lite). - Thinking:
includeThoughts: trueunless reasoning is off; Gemini 2.5 takesthinkingBudget(0 = off, 128 on 2.5 Pro), later models takethinkingLevel(minimalfor off, thenlow/medium/high). A level the model refuses is lowered or removed and the request retried (live:gemini-4-hydrogenrejectsminimal). Parts withthought: truebecome.reasoningSummaryDelta; the API does not always return a summary. - Usage:
promptTokenCount(whole prompt, cached included),cachedContentTokenCount(subset), output =candidatesTokenCount+thoughtsTokenCount, with the latter also reported asreasoningTokens. - Finish reasons:
STOP→endOfTurn(toolCallswhen calls were emitted),MAX_TOKENS→maxTokens,SAFETY,RECITATION,BLOCKLIST,PROHIBITED_CONTENT,SPII,LANGUAGEand the image variants →contentFilter; apromptFeedback.blockReasonwith no candidate →contentFilter;MALFORMED_FUNCTION_CALLand the like → an error. - Errors:
{"error": {"code", "message", "status", "details"}}. A bad key arrives as HTTP 400 with reasonAPI_KEY_INVALID(live) and is reported as unauthorized; aRetryInfo.retryDelayis honoured likeRetry-After. - Model list:
inputTokenLimit,outputTokenLimit,thinkingandsupportedGenerationMethodsfrom the API (source: .providerAPI); models that offergenerateContentbut do not answer with text (speech, image, music, video, agents, embeddings) are filtered by name. Prices and vision / tools badges come from the curated table where present. - Not implemented, deliberately: the newer Interactions API; context caching objects; safety settings; grounding and
other built-in tools; audio / video / file input; structured outputs;
countTokens. - Sources: https://aistudio.google.com/docs/thinking,
/docs/thought-signatures,/docs/pricing(ai.google.dev/gemini-api/docs/* redirects there), read 2026-11-21. The current guides describe the Interactions API, so thegenerateContentfield names above (thinkingConfig,thought,thoughtSignature,usageMetadata,parametersJsonSchema) are confirmed by live requests that day rather than by a reference page.
xAI
- Why Responses: xAI documents Chat Completions as a legacy endpoint; new features go to
/v1/responses. The adapter shares the Responses encoder and decoder with OpenAI. - Differences from OpenAI (live): sampling parameters are accepted;
usage.cost_in_usd_ticksis read intoreportedCostUSD(1e10 ticks per dollar, checked against the listed prices); error bodies are{"code": "...", "error": "<message>"}; a bad key arrives as HTTP 400Incorrect API key providedand is reported as unauthorized; "model not found" messages name the team id, which is removed. - Reasoning:
reasoning: {effort, summary: "auto"}; "off" sendseffort: "none", and when the model refusesnone(grok-4.7) the request is retried withlow. Models whose id containsnon-reasoningnever get the field. - Model list:
/v1/language-modelsgives modalities, prices (units of 1e-4 USD per million tokens) and reasoning efforts;/v1/modelsgivescontext_length. Everything issource: .providerAPI; tools are not reported by the API and are therefore not badged, although they work. - Not implemented, deliberately: server-side search tools, stored responses, encrypted reasoning replay, long-context price tiers (the listed price is the under-200k one).
- Sources: https://docs.x.ai/docs/models, https://docs.x.ai/docs/guides/chat-completions — read 2026-11-21. The Responses guide URL returned 404 that day, so the request and event shapes are confirmed by live requests.
OpenRouter
- Request: OpenAI chat format;
max_tokens,temperature,top_p,seed,stop,tools,reasoning: {effort}("none"for off); routing fromRoutingPreferences:provider.order,provider.allow_fallbacks: false,provider.data_collection: "deny", andmodelsas the fallback list. Usage is not requested: OpenRouter always sends it. - Stream:
: OPENROUTER PROCESSINGcomment lines are skipped;modelandproviderof the first chunk becomereportedModel/servedBy; tool-call fragments are accumulated byindex;delta.reasoning→.reasoningSummaryDelta; the finish reason arrives twice (once more on the usage chunk) and produces one terminal event at[DONE]. - Errors: HTTP errors
{"error": {"code", "message", "metadata"}}; a chunk with a top-levelerrorinside a 200 stream (including as the only chunk) is thrown as a typed error, using its numeric code as the status. - Usage:
prompt_tokens,completion_tokens, cached / cache-write / reasoning details, andusage.cost→reportedCostUSD. - Model list:
context_length,architecture.input_modalities(vision, audio, files),pricing.prompt/.completion/ cache prices (USD per token → per million; negative router prices are dropped),supported_parameters(→ModelInfo.supportedParametersand the tools / reasoning / structured-output badges),top_provider.max_completion_tokens. Models that do not output text are left out. verify():GET /api/v1/key;remainingCreditUSDislimit_remaining, ortotal_credits − total_usagefromGET /api/v1/creditswhen the key has no limit of its own.- Not implemented, deliberately: replay of
reasoning_details(tool cycles work without, live on Claude and Gemini upstreams); the Responses and Messages endpoints;X-OpenRouter-Metadata; providersort/only/ignore/zdr; presets; the:onlineand other plugins. - Sources: https://openrouter.ai/docs/api/reference/streaming,
/errors-and-debugging,/docs/guides/routing/provider-selection, and the pages listed indocs/RESEARCH.md§3 — read 2026-11-21.
Custom OpenAI-compatible endpoint
EndpointProfile.validated()runs on every request: https only, or http with the explicit flag and a host on the local network; no credentials in the URL; no credential-bearing extra headers.- Same encoder and decoder as OpenRouter, with
stream_options: {"include_usage": true}andreasoning_effortfor low / medium / high. Optional fields a server rejects are removed one at a time and the request retried (stream_options,reasoning_effort,seed,top_p,temperature,stop;max_tokensis renamedmax_completion_tokenswhen the server asks for it). - Tolerated server behaviours: no
[DONE]; no tool-call ids (synthesised);finish_reason: "stop"after tool calls;reasoning_contentinstead ofreasoning; a whole JSON completion instead of a stream; HTML error pages (never shown raw). - Model list: ids from
data[]/models[]; context and output limits and capabilities only when the endpoint reports them;source: .providerAPI, or.userfor the model id typed in the profile. No prices. - Verified live against the owner's server (
maclustr-qwen3): list, text, tool round trip.
What was exercised for real on 2026-11-21
- Smoke suite (6 adapters):
verify(),listModels(), streamed text, tool-call round trip (call, result, answer), reasoning summary, image input (a generated red PNG, answered "Red" by all five cloud providers), rejected key. A real 429 ("model at capacity") from xAI was observed during the runs and mapped torateLimited. - Opt-in matrix (
ASTRA_LIVE_MATRIX=1): one bounded request with a temperature and a reasoning effort to every chat model listed — OpenAI 41 (the-protier excluded), Anthropic 15, Gemini 22, xAI 7, custom 1, and 4 OpenRouter models (of 441): 90 of 90 completed. - Tool round trip with reasoning on:
gpt-6.2-sol,gpt-4.1-mini,claude-sonnet-5-5(low and off),claude-opus-5-5,claude-haiku-4-5,claude-haiku-5-5,gemini-4-hydrogen,gemini-2.5-flash-lite,gemini-3.1-flash-lite,grok-4.7,grok-4.20-0309-non-reasoning, and Claude and Gemini through OpenRouter. - Not exercised live: image input on the custom endpoint; prompt-cache hits; rate-limit, quota, overload and content-filter responses (fixtures
only); OpenAI
-promodels; Claude Mythos models (not available to this key); the other 437 OpenRouter models.