POST/v1/chat/completions

Create 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-Keystring

    A 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 example openai/gpt-6-luna) and, where a free promotion covers you, <slug>:free are accepted spellings.

  • messagesarray<object>必須

    The conversation. Roles system, developer, user, assistant, tool.

  • streamboolean

    Stream server-sent events.

    デフォルト: false
  • stream_optionsobject

    {"include_usage": true} adds a final chunk with usage (including cost).

    stream_options
    • include_usageboolean
  • max_completion_tokensinteger

    Output cap. max_tokens is also accepted; when both arrive the smaller wins. A cap above the model's maximum is lowered to it and disclosed.

  • temperaturenumber

    Clamped onto the serving route's range when it accepts a narrower one; dropped where the route does not sample.

  • top_pnumber
  • stopstring | array<string>

    Up to the provider's limit of stop strings.

  • toolsarray<object>

    Function tools. Mark rarely used tools defer_loading: true beside a {"type": "openrouter:tool_search"} entry and the gateway searches them on demand.

  • tool_choicestring | object

    auto, 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 with unsupported_capability when the model has none.

  • reasoning_effortstring

    One of the model's supported_reasoning_efforts. An unsupported effort snaps to the nearest one and is disclosed.

  • web_search_optionsobject

    Ask for web search. Runs natively where the provider searches, otherwise the gateway searches and cites sources.

  • prompt_cache_keystring

    A routing hint for cache affinity. Not a cache guarantee.

  • userstring

    End-user id for your own attribution.

  • providerobject

    OpenRouter's routing-preference object, resolved against the model's own provider routes. Only tightens, never loosens, your organization's policy.

    provider
    • zdrboolean

      true serves 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_fallbacksboolean

      false with order serves only the listed providers; without order, only the first eligible route.

  • gatewayobject

    Per-request retry and routing bounds, never sent to a provider. SDKs send it through extra_body.

    gateway
    • retryobject
      retry
      • max_attempts_per_routeinteger

        Calls per route, including the first. Default 2.

      • max_total_attemptsinteger

        Calls 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).

    • routingobject
      routing
      • allow_fallbacksboolean

        false keeps the first eligible route; no failover.

        デフォルト: true
      • route_idstring

        Pin a route by its opaque handle (route_ + 64 hex), from GET /api/models/{slug}/providers.

レスポンス

  • 200

    The completion. With stream set, chat.completion.chunk events ending in data [DONE].

    レスポンス
    • idstring
    • objectstring
    • createdinteger
    • modelstring
    • providerstring

      Experiential extension. The provider that served this request.

    • choicesarray<object>
    • usageany

      OpenAI usage plus Experiential fields.

      usage
      • prompt_tokensinteger
      • completion_tokensinteger
      • total_tokensinteger
      • prompt_tokens_detailsobject
        prompt_tokens_details
        • cached_tokensinteger
      • completion_tokens_detailsobject
        completion_tokens_details
        • reasoning_tokensinteger
      • costnumber

        USD actually charged to your credits for this request, as a float (promotions and plan discounts already applied). 0 on your own provider key.

      • is_byokboolean

        True when the request ran on your own provider key, which the platform never charges.

      • cost_detailsobject

        Present only in two cases: upstream_inference_cost (USD, your own key: the provider's list charge to you) or list_cost (USD, a platform-funded call charged below list: what it would have cost).

        cost_details
        • upstream_inference_costnumber
        • list_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) or max_tokens->32768(route_maximum).

  • 400

    Invalid request. param names the field; code says why (invalid_parameter, unsupported_parameter, unsupported_capability, refusal, previous_response_not_found). Not charged.

    レスポンス
    • errorobject
      error
      • messagestring

        What went wrong and how to fix it.

      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, api_error.

      • codestring

        The stable error code.

      • paramstring | null

        The request field at fault, when there is one.

      • refusal_reasonenum

        Present only on code: refusal.

        "cyber_policy""cbrn""content_policy""recitation""data_inspection""unspecified"
  • 401

    The key is missing, malformed, expired or revoked.

    レスポンス
    • errorobject
      error
      • messagestring

        What went wrong and how to fix it.

      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, api_error.

      • codestring

        The stable error code.

      • paramstring | null

        The request field at fault, when there is one.

      • refusal_reasonenum

        Present only on code: refusal.

        "cyber_policy""cbrn""content_policy""recitation""data_inspection""unspecified"
  • 402

    The 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.

    レスポンス
    • errorobject
      error
      • messagestring

        What went wrong and how to fix it.

      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, api_error.

      • codestring

        The stable error code.

      • paramstring | null

        The request field at fault, when there is one.

      • refusal_reasonenum

        Present only on code: refusal.

        "cyber_policy""cbrn""content_policy""recitation""data_inspection""unspecified"
  • 403

    model_not_granted (use an id from GET /v1/models), model_location_not_supported, or a zero-data-retention demand no route can meet.

    レスポンス
    • errorobject
      error
      • messagestring

        What went wrong and how to fix it.

      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, api_error.

      • codestring

        The stable error code.

      • paramstring | null

        The request field at fault, when there is one.

      • refusal_reasonenum

        Present only on code: refusal.

        "cyber_policy""cbrn""content_policy""recitation""data_inspection""unspecified"
  • 409

    The Idempotency-Key was reused with a different body, or its original result is gone. Use a fresh key.

    レスポンス
    • errorobject
      error
      • messagestring

        What went wrong and how to fix it.

      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, api_error.

      • codestring

        The stable error code.

      • paramstring | null

        The request field at fault, when there is one.

      • refusal_reasonenum

        Present only on code: refusal.

        "cyber_policy""cbrn""content_policy""recitation""data_inspection""unspecified"
  • 429

    insufficient_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.

    レスポンス
    • errorobject
      error
      • messagestring

        What went wrong and how to fix it.

      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, api_error.

      • codestring

        The stable error code.

      • paramstring | null

        The request field at fault, when there is one.

      • refusal_reasonenum

        Present only on code: refusal.

        "cyber_policy""cbrn""content_policy""recitation""data_inspection""unspecified"
  • 502

    Every provider route failed before any output (all_routes_failed). Retry with backoff.

    レスポンス
    • errorobject
      error
      • messagestring

        What went wrong and how to fix it.

      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, api_error.

      • codestring

        The stable error code.

      • paramstring | null

        The request field at fault, when there is one.

      • refusal_reasonenum

        Present only on code: refusal.

        "cyber_policy""cbrn""content_policy""recitation""data_inspection""unspecified"
  • 503

    gateway_unavailable, gateway_draining, unavailable_route or deadline_exceeded. Retry with backoff, honoring Retry-After when present.

    レスポンス
    • errorobject
      error
      • messagestring

        What went wrong and how to fix it.

      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, api_error.

      • codestring

        The stable error code.

      • paramstring | null

        The request field at fault, when there is one.

      • refusal_reasonenum

        Present only on code: refusal.

        "cyber_policy""cbrn""content_policy""recitation""data_inspection""unspecified"

リクエスト

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