POST/v1/responses

Create a response

The OpenAI Responses API. Continue a conversation with previous_response_id on any gateway server for 30 days after its last turn. State is kept only while your organization stores prompts; an unknown, expired or unstored id is a 400 previous_response_not_found asking you to resend the full conversation.

Under zero-data-retention routing, continuations are refused (zdr_continuation_disabled) unless your organization opts in. The same path also accepts a WebSocket upgrade (the transport the Codex CLI uses).

認証: 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.

  • inputstring | array<object>必須

    A string, or a list of input items (messages, function calls, function call outputs, reasoning items).

  • instructionsstring

    System instructions.

  • previous_response_idstring

    Continue from an earlier response. Kept 30 days from the last turn, only while your organization stores prompts.

  • streamboolean
    デフォルト: false
  • max_output_tokensinteger
  • temperaturenumber
  • top_pnumber
  • toolsarray<object>

    Function tools, web_search, and tool_search with defer_loading tools.

  • tool_choicestring | object
  • textobject

    text.format takes json_schema or json_object for structured output.

  • reasoningobject

    {"effort": "..."} and {"summary": "..."}.

  • includearray<string>

    ["reasoning.encrypted_content"] returns encrypted reasoning items to replay in later turns, without server-side state.

  • prompt_cache_optionsobject

    {"ttl": "12h"} asks for 12-hour prompt caching where the model supports it.

  • storeboolean
  • metadataobject
  • 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 response. With stream set, Responses events ending in response.completed.

    レスポンス
    • idstring

      Pass as previous_response_id to continue.

    • objectstring
    • created_atinteger
    • statusenum
      "completed""incomplete""failed""in_progress"
    • modelstring
    • providerstring

      Experiential extension. The provider that served this request.

    • outputarray<object>
    • usageany
      usage
      • input_tokensinteger
      • input_tokens_detailsobject
        input_tokens_details
        • cached_tokensinteger
      • output_tokensinteger
      • output_tokens_detailsobject
        output_tokens_details
        • reasoning_tokensinteger
      • total_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
  • 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/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-luna", "input": "Name three prime numbers."}'

レスポンス

{
  "id": "resp_8a41c2e09f7b4d3a9c6e1f2b5d8a0c47",
  "object": "response",
  "created_at": 1795132800,
  "status": "completed",
  "model": "gpt-6-luna",
  "provider": "openai",
  "output": [
    {
      "id": "msg_8a41c2e09f7b4d3a9c6e1f2b5d8a0c47",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "2, 3 and 5.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 8,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 20,
    "cost": 0.0000052,
    "is_byok": false
  }
}

https://api.experientiallabs.ai/v1/responses