Infer by Flow7 Usage API

openapi: 3.2.0
info:
  title: Infer by Flow7 Public Usage 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: Usage
  description: Completed metered usage and charge receipts.
paths:
  /v1/usage/receipts/{receiptId}:
    get:
      tags:
      - Usage
      summary: Read one completed usage receipt
      description: Returns a receipt owned by the API key organization. Requires the usage:read scope. Receipt reads remain available when inference is payment-locked so customers can inspect prior charges.
      operationId: getUsageReceipt
      security:
      - bearerAuth: []
      parameters:
      - name: receiptId
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 80
      responses:
        '200':
          description: Completed usage receipt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageReceipt'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  headers:
    RequestId:
      description: Request correlation identifier generated or safely accepted by Infer.
      schema:
        type: string
  schemas:
    GenerationUsage:
      type:
      - object
      - 'null'
      required:
      - unit
      - pricing_key
      - units
      - customer_unit_usd
      properties:
        unit:
          type: string
          enum:
          - generated_image
          - generated_second
        pricing_key:
          type: string
        units:
          type: integer
          minimum: 0
        customer_unit_usd:
          type: number
          minimum: 0
      additionalProperties: false
    ErrorDetail:
      type: object
      required:
      - code
      - message
      - request_id
      properties:
        code:
          type: string
        message:
          type: string
        request_id:
          type:
          - string
          - 'null'
      additionalProperties: true
    ErrorEnvelope:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      additionalProperties: false
    UsageReceipt:
      type: object
      required:
      - id
      - object
      - request_id
      - requested_model
      - resolved_model_class
      - tier
      - price_version
      - usage
      - rates
      - customer_cost_usd
      - cache_status
      - created_at
      - provider_disclosed
      properties:
        id:
          type: string
        object:
          type: string
          const: usage.receipt
        request_id:
          type: string
        requested_model:
          type: string
        resolved_model_class:
          type: string
        tier:
          type: string
          enum:
          - low-cost
          - balanced
          - stable
          - official
          description: Customer-facing Infer service policy selected for this request.
        price_version:
          type: string
          description: 'Immutable price version reference for the request: an opaque identifier (pv_…) that matches the catalog option and response metadata. It reveals no supplier or cost information.'
        usage:
          type: object
          required:
          - input_tokens
          - cached_input_tokens
          - output_tokens
          - cache_write_tokens
          - fresh_input_tokens
          - image_inputs
          properties:
            input_tokens:
              type: integer
              minimum: 0
            cached_input_tokens:
              type: integer
              minimum: 0
            output_tokens:
              type: integer
              minimum: 0
            cache_write_tokens:
              type: integer
              minimum: 0
              description: Input tokens written to prompt cache.
            fresh_input_tokens:
              type: integer
              minimum: 0
              description: Input tokens charged at the fresh-input rate after cache read/write buckets are removed.
            image_inputs:
              type: integer
              minimum: 0
              description: Number of image input parts observed in the admitted request.
          additionalProperties: false
        rates:
          type: object
          required:
          - input_per_million_usd
          - cached_input_per_million_usd
          - output_per_million_usd
          - cache_write_per_million_usd
          - image_input_usd
          properties:
            input_per_million_usd:
              type: number
              minimum: 0
            cached_input_per_million_usd:
              type: number
              minimum: 0
            output_per_million_usd:
              type: number
              minimum: 0
            cache_write_per_million_usd:
              type: number
              minimum: 0
            image_input_usd:
              type: number
              minimum: 0
          additionalProperties: false
        customer_cost_usd:
          type: number
          minimum: 0
        cache_status:
          type: string
          enum:
          - miss
          - hit
          - partial
          - write
          - response_hit
          - not_applicable
          description: Prompt/response cache outcome observed for the request.
        created_at:
          type: string
          format: date-time
        provider_disclosed:
          type: boolean
          const: false
        generation:
          $ref: '#/components/schemas/GenerationUsage'
      additionalProperties: false
  responses:
    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'
    InternalError:
      description: Infer could not complete the operation.
      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'
    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'
  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)