/v1/chat/completionsCreate a chat completion
The OpenAI Chat Completions API. Set stream: true for server-sent events; add stream_options.include_usage: true to get the final usage frame.
Each model is served by a chain of provider routes. A failed route fails over before any output is sent, and the top-level provider names the one that answered. A field the serving route cannot honor is dropped and named in x-experiential-ignored-parameters; a field no route can honor is a 400.
認証: AuthorizationヘッダーにBearer形式のAPIキー
ヘッダー
Idempotency-KeystringA unique string per logical request. A retry with the same key and body replays the first result instead of running again; the same key with a different body is a 409. Keyed responses carry no
usage.cost(a replay must be byte-identical).
リクエストボディ
modelstring必須A slug from
GET /v1/models.<vendor>/<slug>(for exampleopenai/gpt-6-luna) and, where a free promotion covers you,<slug>:freeare accepted spellings.messagesarray<object>必須The conversation. Roles
system,developer,user,assistant,tool.streambooleanStream server-sent events.
stream_optionsobject{"include_usage": true}adds a final chunk withusage(includingcost).stream_options
include_usageboolean
max_completion_tokensintegerOutput cap.
max_tokensis also accepted; when both arrive the smaller wins. A cap above the model's maximum is lowered to it and disclosed.temperaturenumberClamped onto the serving route's range when it accepts a narrower one; dropped where the route does not sample.
top_pnumberstopstring | array<string>Up to the provider's limit of stop strings.
toolsarray<object>Function tools. Mark rarely used tools
defer_loading: truebeside a{"type": "openrouter:tool_search"}entry and the gateway searches them on demand.tool_choicestring | objectauto,none,required, or a named function.response_formatobject{"type": "json_object"}or{"type": "json_schema", "json_schema": {...}}. Routes the request to structured-output routes; refused withunsupported_capabilitywhen the model has none.reasoning_effortstringOne of the model's
supported_reasoning_efforts. An unsupported effort snaps to the nearest one and is disclosed.web_search_optionsobjectAsk for web search. Runs natively where the provider searches, otherwise the gateway searches and cites sources.
prompt_cache_keystringA routing hint for cache affinity. Not a cache guarantee.
userstringEnd-user id for your own attribution.
providerobjectOpenRouter's routing-preference object, resolved against the model's own provider routes. Only tightens, never loosens, your organization's policy.
provider
zdrbooleantrueserves only zero-data-retention routes for this request, or refuses with a 403 naming the excluded providers.onlyarray<string>Keep only these providers.
ignorearray<string>Drop these providers.
orderarray<string>Try these providers first, in order; the rest stay as fallbacks.
allow_fallbacksbooleanfalsewithorderserves only the listed providers; withoutorder, only the first eligible route.
gatewayobjectPer-request retry and routing bounds, never sent to a provider. SDKs send it through
extra_body.gateway
retryobjectretry
max_attempts_per_routeintegerCalls per route, including the first. Default 2.
max_total_attemptsintegerCalls in total, including retries and fallbacks. Default 8.
backoffobject{"type": "none"}or{"type": "exponential", "base_delay_ms", "max_delay_ms", "multiplier"}(defaults 500, 8000, 2).
routingobjectrouting
allow_fallbacksbooleanfalsekeeps the first eligible route; no failover.route_idstringPin a route by its opaque handle (
route_+ 64 hex), fromGET /api/models/{slug}/providers.
レスポンス
200The completion. With stream set, chat.completion.chunk events ending in data [DONE].
レスポンス
idstringobjectstringcreatedintegermodelstringproviderstringExperiential extension. The provider that served this request.
choicesarray<object>usageanyOpenAI usage plus Experiential fields.
usage
prompt_tokensintegercompletion_tokensintegertotal_tokensintegerprompt_tokens_detailsobjectprompt_tokens_details
cached_tokensinteger
completion_tokens_detailsobjectcompletion_tokens_details
reasoning_tokensinteger
costnumberUSD actually charged to your credits for this request, as a float (promotions and plan discounts already applied).
0on your own provider key.is_byokbooleanTrue when the request ran on your own provider key, which the platform never charges.
cost_detailsobjectPresent only in two cases:
upstream_inference_cost(USD, your own key: the provider's list charge to you) orlist_cost(USD, a platform-funded call charged below list: what it would have cost).cost_details
upstream_inference_costnumberlist_costnumber
x-experiential-ignored-parametersarray<string>Present when the gateway changed your request: each entry names a field and what happened, for example
temperature->dropped(unsupported_by_provider)ormax_tokens->32768(route_maximum).
400Invalid request. param names the field; code says why (invalid_parameter, unsupported_parameter, unsupported_capability, refusal, previous_response_not_found). Not charged.
レスポンス
errorobjecterror
messagestringWhat went wrong and how to fix it.
typestringFor example
invalid_request_error,authentication_error,permission_error,rate_limit_error,insufficient_quota,api_error.codestringThe stable error code.
paramstring | nullThe request field at fault, when there is one.
refusal_reasonenumPresent only on
code: refusal.
401The key is missing, malformed, expired or revoked.
レスポンス
errorobjecterror
messagestringWhat went wrong and how to fix it.
typestringFor example
invalid_request_error,authentication_error,permission_error,rate_limit_error,insufficient_quota,api_error.codestringThe stable error code.
paramstring | nullThe request field at fault, when there is one.
refusal_reasonenumPresent only on
code: refusal.
402The organization must act first: card_required, email_unverified, org_under_review, free_tier_requires_payment or promotion_ended. The message names the step; retrying does not help.
レスポンス
errorobjecterror
messagestringWhat went wrong and how to fix it.
typestringFor example
invalid_request_error,authentication_error,permission_error,rate_limit_error,insufficient_quota,api_error.codestringThe stable error code.
paramstring | nullThe request field at fault, when there is one.
refusal_reasonenumPresent only on
code: refusal.
403model_not_granted (use an id from GET /v1/models), model_location_not_supported, or a zero-data-retention demand no route can meet.
レスポンス
errorobjecterror
messagestringWhat went wrong and how to fix it.
typestringFor example
invalid_request_error,authentication_error,permission_error,rate_limit_error,insufficient_quota,api_error.codestringThe stable error code.
paramstring | nullThe request field at fault, when there is one.
refusal_reasonenumPresent only on
code: refusal.
409The Idempotency-Key was reused with a different body, or its original result is gone. Use a fresh key.
レスポンス
errorobjecterror
messagestringWhat went wrong and how to fix it.
typestringFor example
invalid_request_error,authentication_error,permission_error,rate_limit_error,insufficient_quota,api_error.codestringThe stable error code.
paramstring | nullThe request field at fault, when there is one.
refusal_reasonenumPresent only on
code: refusal.
429insufficient_quota (out of credits, over a spend limit, or the model needs a purchase) and promo_credits_now (a free promotion is used up): add credits, the message names the step. rate_limit_exceeded, free_limit_reached, admission_capacity_exceeded: wait Retry-After seconds and retry.
レスポンス
errorobjecterror
messagestringWhat went wrong and how to fix it.
typestringFor example
invalid_request_error,authentication_error,permission_error,rate_limit_error,insufficient_quota,api_error.codestringThe stable error code.
paramstring | nullThe request field at fault, when there is one.
refusal_reasonenumPresent only on
code: refusal.
502Every provider route failed before any output (all_routes_failed). Retry with backoff.
レスポンス
errorobjecterror
messagestringWhat went wrong and how to fix it.
typestringFor example
invalid_request_error,authentication_error,permission_error,rate_limit_error,insufficient_quota,api_error.codestringThe stable error code.
paramstring | nullThe request field at fault, when there is one.
refusal_reasonenumPresent only on
code: refusal.
503gateway_unavailable, gateway_draining, unavailable_route or deadline_exceeded. Retry with backoff, honoring Retry-After when present.
レスポンス
errorobjecterror
messagestringWhat went wrong and how to fix it.
typestringFor example
invalid_request_error,authentication_error,permission_error,rate_limit_error,insufficient_quota,api_error.codestringThe stable error code.
paramstring | nullThe request field at fault, when there is one.
refusal_reasonenumPresent only on
code: refusal.
リクエスト
curl https://api.experientiallabs.ai/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-luna",
"messages": [{"role": "user", "content": "Write a haiku about latency."}]
}'
レスポンス
{
"id": "chatcmpl_5d0f3b8e2a7c41e9b6f1a4c8d2e7f903",
"object": "chat.completion",
"created": 1795132800,
"model": "gpt-6-luna",
"provider": "openai",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Packets cross the sea,\nmilliseconds pile like snow,\nthe spinner turns on."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 24,
"completion_tokens": 21,
"total_tokens": 45,
"prompt_tokens_details": {
"cached_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0
},
"cost": 0.0000129,
"is_byok": false
}
}https://api.experientiallabs.ai/v1/chat/completions