Infer by Flow7 Inference API

openapi: 3.2.0
info:
  title: Infer by Flow7 Public Inference API
  summary: Authenticated Responses, Chat Completions, and Anthropic Messages inference plus public catalog/status metadata.
  description: 'This description covers Infer''s public paid integration surface: authenticated Responses, OpenAI Chat Completions, Anthropic Messages, the authenticated model/receipt APIs, and unauthenticated catalog/status resources. All inference skins share one routing, wallet, cache, media, privacy, and receipt engine. Public registration creates an account; the account email must be verified, the wallet must be funded, and a scoped API key must be created before metered inference. Route availability is dynamic, so read the public status resource immediately before use. Infer does not attest an upstream provider identity.'
  termsOfService: https://infer.flow7.org/terms
  contact:
    name: Infer by Flow7 support
    url: https://infer.flow7.org/support
  version: 0.9.0
  x-infer-access:
    mode: public-paid
    url: https://infer.flow7.org/signup
    automaticAccountProvisioning: true
    emailVerificationRequired: true
    fundingRequiredForLiveInference: true
  x-infer-streaming:
    mode: live-incremental
    providerDeltasForwarded: true
    reasoningDeltas: true
    toolArgumentDeltas: true
    heartbeatSeconds: 15
    inferTotalGenerationDeadline: null
    finalSettlementMetadata: true
    clientDisconnectCancelsUpstream: true
    clientDisconnectCharge: generated_usage_up_to_reservation
servers:
- url: https://infer.flow7.org
  description: Infer's production origin. Read /api/public/status for current route availability.
tags:
- name: Inference
  description: Authenticated customer inference operations.
paths:
  /v1/responses:
    post:
      tags:
      - Inference
      summary: Create a Responses-style inference request
      description: 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.
      operationId: createResponse
      security:
      - bearerAuth: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Stable retry key scoped to the organization. The header takes precedence over the body field. When neither is supplied, Infer generates a one-use key; clients that may retry should send a stable value explicitly. A failed operation keeps its key as a terminal failure record; retry that operation with a new key.
        schema:
          type: string
          minLength: 1
          maxLength: 200
      - name: X-Session-Affinity
        in: header
        required: false
        description: Optional stable session identifier. relay.session_id in the JSON body takes precedence.
        schema:
          type: string
          minLength: 1
          maxLength: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateResponseRequest'
      responses:
        '200':
          description: 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.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ResponseEventStream'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  schemas:
    ResponseEventStream:
      type: string
      description: Live incremental Responses SSE. Infer forwards upstream reasoning, text, and function-call deltas as they arrive, emits keepalive comments during quiet periods, closes each output item, and ends with response.completed containing settled usage and relay receipt metadata.
    ResponseInputItem:
      type: object
      properties:
        type:
          type: string
          description: Responses item type, including message, function_call, or function_call_output.
        role:
          type: string
          enum:
          - user
          - assistant
          - system
          - developer
        content:
          oneOf:
          - type: string
            minLength: 1
          - type: array
            minItems: 1
            items:
              oneOf:
              - type: string
              - $ref: '#/components/schemas/InputTextPart'
              - $ref: '#/components/schemas/InputImagePart'
              - $ref: '#/components/schemas/InputFilePart'
              - $ref: '#/components/schemas/InputAudioPart'
              - $ref: '#/components/schemas/InputVideoPart'
        call_id:
          type: string
        name:
          type: string
        arguments:
          type: string
        output: {}
      description: Responses input item. Message content supplies extractable text; native tool-loop objects may omit content and use call_id, arguments, or output instead.
      additionalProperties: true
    InputImagePart:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          const: input_image
        image_url:
          type: string
          description: Image URL or data URL accepted by the upstream Responses model.
        file_id:
          type: string
        detail:
          type: string
          enum:
          - auto
          - low
          - high
      anyOf:
      - required:
        - image_url
      - required:
        - file_id
      additionalProperties: true
      description: Responses image input. Infer only admits it to a native Responses route that advertises vision support.
    ResponseUsage:
      type: object
      required:
      - input_tokens
      - input_tokens_details
      - output_tokens
      - output_tokens_details
      - total_tokens
      properties:
        input_tokens:
          type: integer
          minimum: 0
        input_tokens_details:
          type: object
          required:
          - cached_tokens
          properties:
            cached_tokens:
              type: integer
              minimum: 0
            cache_write_tokens:
              type: integer
              minimum: 0
              description: Input tokens written into a provider prompt cache for this request.
          additionalProperties: true
        output_tokens:
          type: integer
          minimum: 0
        output_tokens_details:
          type: object
          required:
          - reasoning_tokens
          properties:
            reasoning_tokens:
              type: integer
              minimum: 0
          additionalProperties: true
        total_tokens:
          type: integer
          minimum: 0
      additionalProperties: true
    ErrorDetail:
      type: object
      required:
      - code
      - message
      - request_id
      properties:
        code:
          type: string
        message:
          type: string
        request_id:
          type:
          - string
          - 'null'
      additionalProperties: true
    InputAudioPart:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          const: input_audio
      additionalProperties: true
      description: Provider-compatible Responses audio input. Infer passes the native content object through only when the route advertises audio support.
    ErrorEnvelope:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      additionalProperties: false
    CreateResponseRequest:
      type: object
      required:
      - model
      - input
      properties:
        model:
          type: string
          pattern: ^infer/[a-z0-9._/-]+:(low-cost|balanced|stable|official)$
          description: Canonical selector from the model list or public catalog.
        input:
          $ref: '#/components/schemas/ResponseInput'
        max_output_tokens:
          type: integer
          minimum: 1
          description: 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:
          type: boolean
          default: false
        tools:
          type: array
          items:
            type: object
            additionalProperties: true
          description: Responses-style function tools. The selected route must advertise tool support.
        text:
          type: object
          additionalProperties: true
          description: Responses text options, including a structured-output format. Route support is required.
        response_format:
          type: object
          additionalProperties: true
          description: Accepted structured-output shorthand. Route support is required.
        reasoning:
          type: object
          additionalProperties: true
        relay:
          $ref: '#/components/schemas/RelayRequestOptions'
        session_id:
          type: string
          minLength: 1
          maxLength: 200
          description: Top-level session identifier accepted for compatibility. relay.session_id is preferred.
        idempotency_key:
          type: string
          minLength: 1
          maxLength: 200
          description: Body fallback for Idempotency-Key. The header wins when both are present; Infer generates a one-use key when neither is supplied.
        request_id:
          type: string
          description: Optional client correlation value.
          maxLength: 200
        cache_control:
          type: object
          additionalProperties: true
          description: Optional provider-compatible prompt-cache control. Cache writes are metered separately. Not allowed with relay.privacy=zero-retention.
        prompt_cache_key:
          type: string
          maxLength: 256
          description: 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:
          type: array
          items:
            type: string
          description: Optional native Responses modality hint. Actual media input is still admitted only when the selected route supports it.
      description: 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.
      additionalProperties: true
    RelayResponseMetadata:
      type: object
      required:
      - receipt_id
      - price_version
      - tier
      - resolved_model_class
      - cache_status
      - environment
      - provider_disclosed
      - customer_cost_usd
      properties:
        receipt_id:
          type: string
        price_version:
          type: string
          description: 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:
          type: string
          enum:
          - low-cost
          - balanced
          - stable
          - official
        resolved_model_class:
          type: string
        cache_status:
          type: string
          enum:
          - hit
          - partial
          - miss
        environment:
          type: string
          enum:
          - live
        provider_disclosed:
          type: boolean
          const: false
        customer_cost_usd:
          type: number
          minimum: 0
        idempotent_replay:
          type: boolean
      additionalProperties: true
    ResponseObject:
      type: object
      required:
      - id
      - object
      - created_at
      - status
      - model
      - output
      - output_text
      - usage
      - relay
      properties:
        id:
          type: string
        object:
          type: string
          const: response
        created_at:
          type: integer
        status:
          type: string
          const: completed
        model:
          type: string
          description: The requested Infer selector. Read relay.resolved_model_class for the class that completed.
        output:
          type: array
          items:
            type: object
            additionalProperties: true
        output_text:
          type: string
        usage:
          $ref: '#/components/schemas/ResponseUsage'
        relay:
          $ref: '#/components/schemas/RelayResponseMetadata'
      additionalProperties: true
    InputFilePart:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          const: input_file
        file_url:
          type: string
        file_id:
          type: string
        file_data:
          type: string
        filename:
          type: string
      additionalProperties: true
      description: Responses file/PDF input. Route support is required.
    RelayRequestOptions:
      type: object
      properties:
        session_id:
          type: string
          minLength: 1
          maxLength: 200
        privacy:
          type: string
          enum:
          - standard
          - no-training
          - zero-retention
          default: standard
      additionalProperties: false
    InputTextPart:
      type: object
      properties:
        type:
          type: string
        text:
          type: string
        input_text:
          type: string
      anyOf:
      - required:
        - text
      - required:
        - input_text
      additionalProperties: true
    ResponseInput:
      oneOf:
      - type: string
        minLength: 1
      - type: array
        minItems: 1
        items:
          oneOf:
          - type: string
          - $ref: '#/components/schemas/ResponseInputItem'
      description: 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.
      examples:
      - - type: message
          role: user
          content:
          - type: input_text
            text: Check the repository state, then use the approved read-only tool.
        - type: function_call
          call_id: call_example
          name: read_repository_state
          arguments: '{}'
        - type: function_call_output
          call_id: call_example
          output: No uncommitted changes.
    InputVideoPart:
      type: object
      required:
      - type
      - video_url
      properties:
        type:
          type: string
          const: input_video
        video_url:
          type: string
          description: Remote video URL or base64 data URL.
      additionalProperties: true
      description: Infer video-input extension. On a video-capable selected route Infer may use a verified Chat Completions upstream wire format internally because video is not native to every Responses provider surface.
  responses:
    UnprocessableEntity:
      description: A selector, input, output limit, session identifier, or routing option is invalid.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Unauthorized:
      description: A valid Bearer API key is required.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Unavailable:
      description: Live inference is disabled, no eligible route has capacity, or no route completed within the retry budget.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: No active price exists for the requested selector in this environment.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    PaymentRequired:
      description: The wallet cannot cover the request's reservation.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Forbidden:
      description: The key, organization, environment, or scope cannot perform this operation.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    PayloadTooLarge:
      description: The input or request body exceeds a configured limit.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    InternalError:
      description: Infer could not complete the operation.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    RateLimited:
      description: The request rate limit or an API-key spend ceiling was reached.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          description: Delay in seconds supplied for coarse request-rate limits.
          schema:
            type: integer
            minimum: 0
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Conflict:
      description: The idempotency key is in progress, expired, or otherwise cannot be replayed.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    BadRequest:
      description: The request could not be processed.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  headers:
    RequestId:
      description: Request correlation identifier generated or safely accepted by Infer.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Infer API key
      description: Infer API key. Do not place it in a URL, prompt, support request, or public diagnostic output.
    anthropicApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Infer API key accepted on the Anthropic Messages compatibility endpoint. Bearer authentication is also supported.
externalDocs:
  description: Human-readable Infer API documentation
  url: https://infer.flow7.org/docs
x-provenance:
  method: harvested
  publisher: Infer by Flow7
  source: https://infer.flow7.org/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)