Create a model response

POST/v1/responses

Create a model response.

Drop-in compatible with OpenAI's Responses API, for every provider the gateway serves: the body is a Responses request and the answer a Responses object (or, with "stream": true, a text/event-stream of Responses events: response.created, response.output_item.added, response.output_text.delta, response.function_call_arguments.delta, ..., response.completed). With an OpenAI key the request goes to OpenAI as sent (apart from what the gateway sets: the model, guardrail redactions, routing overrides), so every Responses feature works. With a key for another provider (Anthropic, Gemini, Vertex AI, Groq, Mistral, ...) it is translated: text, images, files, function tools and their calls and outputs, tool_choice, max_output_tokens, temperature, top_p, reasoning.effort and text.format carry over, and Claude's thinking comes back as reasoning items to send back on the next turn. What only OpenAI can do is a 400 naming it on another provider: built-in tools (web_search, file_search, ...), their call items, previous_response_id, conversation, prompt and background. A response from another provider is not stored (store is false).

Credentials, in this order: x-virtual-key; Authorization: Bearer vk-... (what the OpenAI SDK sends from OPENAI_API_KEY); x-config (a routing config, with x-organization); x-api-key; any other Authorization: Bearer token. A value starting vk- is a virtual key's API key, BYOK or PLATFORM; anything else is the provider's own key (OpenAI, unless x-provider names another provider). No credential is a 401.

What the gateway adds is the same as on chat completions: the virtual key's checks and the plan's limits, the response cache (x-cache-mode), retries and fallbacks (x-retry-*, x-fallback-*, which can cross providers), routing configs (x-config), the tool-result scan on function_call_output items, and guardrails (the virtual key's plus x-guardrail) on the input and the answer. The response carries x-cache-status, x-retry-count, x-fallback-provider (when a fallback answered), x-virtual-key-slug and x-guardrail-status (when guardrails apply). file_id values that are VectorAxis file ids (vxf-...) uploaded with the same virtual key are replaced by the provider's file id.

Streaming. Retries and fallbacks apply until the first event, and a cache hit is replayed as events. A failure after the first event (a provider error mid-answer, an output guardrail BLOCK) ends the stream with an error event. On a stream, x-guardrail-status reports the input checks only.

Errors are in OpenAI's shape, {"error":{"message","type","param","code"}}: 400 for an invalid request or one the provider cannot take, 401 for a missing or invalid credential, 403 when the virtual key is disabled, expired or out of credit or the model is not allowed, 422 when a guardrail blocks (code: guardrail_blocked, with x-guardrail-status: BLOCK), 429 for a rate limit. A provider's error keeps its status and message.

Compatible with the OpenAI Responses API. The request and response bodies are the provider's own format, passed through by the gateway: see the OpenAI Responses API reference for every field. The credentials and headers below are what VectorAxis adds.

Authorization

AuthorizationBearer <slug>.<secret>
A virtual key's API key (vk-....<secret>), as Authorization: Bearer. What the OpenAI SDK sends from its api_key. Used by the inference endpoints.
orx-virtual-keyheader
A virtual key's API key in the x-virtual-key header, for clients that keep Authorization for something else.
orx-api-keyheader
Direct credentials: the provider's own API key in x-api-key, with the provider named in x-provider (for example openai). On /v1/messages a virtual key is accepted in x-api-key too, which is what the Claude SDK sends.

Headers

x-providerstring
With direct credentials: the provider x-api-key belongs to, for example openai or anthropic (case and dashes are normalised). Not used with a virtual key.
x-cache-modestring
Turns on the response cache for this request: simple (exact match) or semantic (a similar earlier request). Without it nothing is read from or written to the cache. The outcome is in the x-cache-status response header.
x-cache-ttlinteger<int32>
How long, in seconds, a response stored by this request stays in the cache. When the organization has a cache TTL set, this can shorten it but not extend it.
x-cache-force-refreshboolean
true skips the cache lookup, calls the provider and replaces the stored response (x-cache-status: REFRESH).
x-retry-countinteger<int32>
How many times to retry a failed provider call, 0 to 5. Without the header, chat completions, Claude Messages and prompt completions do not retry, and the other endpoints retry up to 3 times. Retries back off exponentially from 1 second and honour a numeric Retry-After. The number made is in the x-retry-count response header.
x-retry-status-codesstring
Comma-separated provider status codes to retry on. Default 429,500,502,503,504,529.
x-fallback-1-providerstring
The provider to try when the request fails after its retries. Up to five fallbacks, tried in order: x-fallback-1-* to x-fallback-5-*. The provider that answered is in the x-fallback-provider response header.
x-fallback-1-api-keystring
The API key for fallback 1's provider.
x-fallback-1-modelstring
The model fallback 1 uses. Optional: the request's own model otherwise.
x-guardrailstring
A guardrail slug (gr-...) to apply to this request, in addition to any the virtual key carries. A BLOCK is a 422 with x-guardrail-status: BLOCK.
x-configstring
A routing config slug: the config chooses the provider, model and key (load balancing, fallback or conditional routing). Without a virtual key, send x-organization with it to name the config's organization.
x-organizationstring
The organization slug. Required with x-config; with a virtual key the key's organization is used.
x-workspace-idstring
Workspace id (UUID) to attribute the request to in logs and analytics.
x-metadatastring
A JSON object of your own string key/value pairs, stored with the request's log entry for filtering.
x-prompt-slugstring
Attributes the request to a prompt from the prompt library, for its analytics.
x-prompt-versioninteger<int32>
The prompt version the request used, with x-prompt-slug.
x-vertex-projectstring
Google Vertex AI keys only: the GCP project to call, instead of the one stored with the key.
x-vertex-regionstring
Google Vertex AI keys only: the region to call (or global), instead of the one stored with the key.
anthropic-betastring
Anthropic beta features, comma-separated (for example context-management-2025-06-27). Forwarded to Anthropic and Claude on Vertex only; at most 32 names of lower-case letters, digits and dashes.

Responses

200application/json

The response. With stream: true, a stream of Responses events ending with response.completed.

Request

curl -X POST "https://api.vectoraxis.ai/v1/responses" \
  -H "Authorization: Bearer $VECTORAXIS_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": {}
}'

Response 200

{}

VectorAxis is built by GK Labs, a member of NVIDIA Inception.