---
title: "Create a Responses-style inference request"
method: POST
path: "/v1/responses"
tags: ["Inference"]
---

# Create a Responses-style inference request

`POST /v1/responses`

## Request

- Base URL: `https://infer.flow7.org`
- URL: `https://infer.flow7.org/v1/responses`
- Auth: HTTP bearer

Authenticates an Infer API key, validates a canonical model selector and routing policy, reserves the request's spend ceiling, and returns a charge record reference after completion. With stream=true, Infer opens the provider stream before returning HTTP 200, forwards reasoning, text, and function-call deltas in real time, emits keepalive comments during quiet reasoning periods, and places settled usage, cache accounting, final charge, and receipt metadata in response.completed. Infer does not impose a generation wall-clock timeout while the client and upstream connection remain alive; provider-originated timeout/error events remain possible. Client disconnect cancels the upstream stream and reconciles the reservation. Exact model-family selection does not cross into another model family. Route eligibility still depends on current capabilities, privacy, health, authorization, margin, and capacity. Read /api/public/status immediately before use. A response model name, streamed output, charge, or receipt does not attest an upstream provider identity or satisfy Infer's separate strict supplier-evidence standard.

## Headers

- `Idempotency-Key` string
- `X-Session-Affinity` string

## Request body

- CreateResponseRequest: Infer documents the stable fields it validates or uses for routing. Prompt-cache controls are supported on compatible routes; cache reads and cache writes are metered separately, and cache controls are rejected when they conflict with zero-retention. Additional Responses fields may pass through on native Responses routes and should not be assumed portable across every selected route.
  - `model` string, required: Canonical selector from the model list or public catalog.
  - `input` union, required: Text or a list of Infer canonical input items. Message content may include text, image, file/PDF, audio, or video parts. Infer selects an upstream wire protocol per admitted capability; media is never silently discarded.
    - string
    - union[]
      - union
        - string
        - ResponseInputItem: Responses input item. Message content supplies extractable text; native tool-loop objects may omit content and use call_id, arguments, or output instead.
          - `type` string: Responses item type, including message, function_call, or function_call_output.
          - `role` 'user' | 'assistant' | 'system' | 'developer'
          - `content` union
            - string
            - union[]
              - …
          - `call_id` string
          - `name` string
          - `arguments` string
          - `output` unknown
  - `max_output_tokens` integer: Output ceiling, sent upstream and covered by the wallet reservation. When omitted, Infer sets it to the output room of the routes serving the request, at most 32768 tokens. A reply that reaches it ends with status "incomplete" and incomplete_details, and is charged for what was generated.
  - `stream` boolean
  - `tools` object[]: Responses-style function tools. The selected route must advertise tool support.
  - `text` object: Responses text options, including a structured-output format. Route support is required.
  - `response_format` object: Accepted structured-output shorthand. Route support is required.
  - `reasoning` object
  - `relay` RelayRequestOptions
    - `session_id` string
    - `privacy` 'standard' | 'no-training' | 'zero-retention'
  - `session_id` string: Top-level session identifier accepted for compatibility. relay.session_id is preferred.
  - `idempotency_key` string: Body fallback for Idempotency-Key. The header wins when both are present; Infer generates a one-use key when neither is supplied.
  - `request_id` string: Optional client correlation value.
  - `cache_control` object: Optional provider-compatible prompt-cache control. Cache writes are metered separately. Not allowed with relay.privacy=zero-retention.
  - `prompt_cache_key` string: Optional provider prompt-cache routing key. When relay.session_id is used on a supported native Responses route, Infer also derives a private organization-scoped sticky cache key automatically. Not allowed with zero-retention.
  - `modalities` string[]: Optional native Responses modality hint. Actual media input is still admitted only when the selected route supports it.

## Response `200`

Completed response as JSON, or Responses events when stream is true. Infer currently assembles the completed upstream result into an SSE event sequence; this description does not promise token-by-token upstream delivery.

- ResponseObject
  - `id` string, required
  - `object` 'response', required
  - `created_at` integer, required
  - `status` 'completed', required
  - `model` string, required: The requested Infer selector. Read relay.resolved_model_class for the class that completed.
  - `output` object[], required
  - `output_text` string, required
  - `usage` ResponseUsage, required
    - `input_tokens` integer, required
    - `input_tokens_details` object, required
      - `cached_tokens` integer, required
      - `cache_write_tokens` integer: Input tokens written into a provider prompt cache for this request.
    - `output_tokens` integer, required
    - `output_tokens_details` object, required
      - `reasoning_tokens` integer, required
    - `total_tokens` integer, required
  - `relay` RelayResponseMetadata, required
    - `receipt_id` string, required
    - `price_version` string, required: Opaque reference (pv_…) to the immutable price version that priced this request. It matches the catalog option and the usage receipt and reveals no supplier or cost information.
    - `tier` 'low-cost' | 'balanced' | 'stable' | 'official', required
    - `resolved_model_class` string, required
    - `cache_status` 'hit' | 'partial' | 'miss', required
    - `environment` 'live', required
    - `provider_disclosed` false, required
    - `customer_cost_usd` number, required
    - `idempotent_replay` boolean

## Other responses

- `400`: The request could not be processed.
- `401`: A valid Bearer API key is required.
- `402`: The wallet cannot cover the request's reservation.
- `403`: The key, organization, environment, or scope cannot perform this operation.
- `404`: No active price exists for the requested selector in this environment.
- `409`: The idempotency key is in progress, expired, or otherwise cannot be replayed.
- `413`: The input or request body exceeds a configured limit.
- `422`: A selector, input, output limit, session identifier, or routing option is invalid.
- `429`: The request rate limit or an API-key spend ceiling was reached.
- `500`: Infer could not complete the operation.
- `503`: Live inference is disabled, no eligible route has capacity, or no route completed within the retry budget.

---

[API](https://skmtc.dev/flow7/apis/infer-by-flow7-public-api.md) · [All operations](https://skmtc.dev/flow7/apis/infer-by-flow7-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flow7/apis/infer-by-flow7-public-api/revisions/e73ecffd3cf3?raw)