Infer by Flow7 Generation API

openapi: 3.2.0
info:
  title: Infer by Flow7 Public Generation 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: Generation
paths:
  /v1/images/generations:
    post:
      tags:
      - Generation
      summary: Generate one image with GPT Image 2
      operationId: generateImage
      security:
      - bearerAuth: []
      description: Native image generation with exact per-image reservation before dispatch. The Stable generation price matrix is published in /api/public/catalog. Provider identity and provider asset URLs remain private. URL results use short-lived Infer-signed content URLs; b64_json bytes are returned once and are not retained. Infer performs no automatic paid generation retry. A post-dispatch transport ambiguity leaves the reservation locked rather than guessing about provider spend.
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Stable retry key scoped to the organization. Strongly recommended for any paid generation submission. Ambiguous post-dispatch outcomes are never automatically retried.
        schema:
          type: string
          minLength: 1
          maxLength: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageGenerationRequest'
      responses:
        '200':
          description: Completed image generation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageGenerationResponse'
        '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'
  /v1/images/edits:
    post:
      tags:
      - Generation
      summary: Edit one image using public HTTPS references
      operationId: editImage
      security:
      - bearerAuth: []
      description: Native GPT Image 2 editing through either JSON public-HTTPS image references or one multipart PNG/JPEG/WebP upload up to 20 MiB. File bytes are hashed for idempotency, forwarded directly, and never persisted to Neon. Financial and retry semantics are the same as image generation.
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Stable retry key scoped to the organization. Strongly recommended for any paid generation submission. Ambiguous post-dispatch outcomes are never automatically retried.
        schema:
          type: string
          minLength: 1
          maxLength: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageEditRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ImageEditMultipartRequest'
      responses:
        '200':
          description: Completed image edit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageGenerationResponse'
        '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'
  /v1/images/{requestId}/content:
    get:
      tags:
      - Generation
      summary: Read a short-lived signed Infer image asset
      operationId: getImageContent
      security: []
      description: Streams the generated image through Infer after validating the short-lived signature. The supplier asset URL is never exposed.
      parameters:
      - name: requestId
        in: path
        required: true
        schema:
          type: string
      - name: expires
        in: query
        required: true
        schema:
          type: integer
      - name: signature
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: PNG image
          content:
            image/png:
              schema:
                type: string
                format: binary
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          description: Upstream asset unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAICompatErrorEnvelope'
  /v1/videos:
    post:
      tags:
      - Generation
      summary: Create an asynchronous Seedance video task
      operationId: createVideo
      security:
      - bearerAuth: []
      description: Reserves the full per-second Stable price ceiling before native submission. Returns an Infer-owned task id. A five-minute maintenance reconciler polls terminal state even if the client never does. No automatic paid retry is performed.
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Stable retry key scoped to the organization. Strongly recommended for any paid generation submission. Ambiguous post-dispatch outcomes are never automatically retried.
        schema:
          type: string
          minLength: 1
          maxLength: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoCreateRequest'
      responses:
        '202':
          description: Video task accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoObject'
        '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'
  /v1/videos/{requestId}:
    get:
      tags:
      - Generation
      summary: Read and reconcile a Seedance video task
      operationId: getVideo
      security:
      - bearerAuth: []
      description: Reads current state for an Infer-owned video task. Terminal completion settles the locked reservation exactly once; terminal failure releases it exactly once. Temporary provider errors leave the reservation intact.
      parameters:
      - name: requestId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Current video task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoObject'
        '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'
  /v1/videos/{requestId}/content:
    get:
      tags:
      - Generation
      summary: Download a completed video through Infer
      operationId: getVideoContent
      security:
      - bearerAuth: []
      description: Streams a completed video through Infer to the owning API-key organization. Supplier task ids and content URLs remain private.
      parameters:
      - name: requestId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: MP4 video
          content:
            video/mp4:
              schema:
                type: string
                format: binary
        '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:
  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'
  schemas:
    ErrorDetail:
      type: object
      required:
      - code
      - message
      - request_id
      properties:
        code:
          type: string
        message:
          type: string
        request_id:
          type:
          - string
          - 'null'
      additionalProperties: true
    ImageEditMultipartRequest:
      type: object
      required:
      - model
      - prompt
      - image
      properties:
        model:
          type: string
          description: gpt-image-2 or infer/gpt-image-2:stable.
        prompt:
          type: string
          minLength: 1
          maxLength: 32000
        image:
          type: string
          format: binary
          description: Exactly one PNG, JPEG, or WebP file. Maximum 20 MiB.
        n:
          type: integer
          const: 1
          default: 1
        quality:
          type: string
          enum:
          - medium
          - high
          default: medium
        size:
          type: string
          pattern: ^[0-9]+x[0-9]+$
          default: 1024x1024
        response_format:
          type: string
          enum:
          - url
          - b64_json
          default: url
        output_format:
          type: string
          const: png
          default: png
        stream:
          type: boolean
          const: false
          default: false
      additionalProperties: false
    ErrorEnvelope:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      additionalProperties: false
    GenerationRelayMetadata:
      type: object
      properties:
        request_id:
          type: string
        receipt_id:
          type: string
        price_version:
          type: string
          description: Opaque reference (pv_…) to the immutable price version that priced this generation.
        tier:
          type: string
          const: stable
        customer_cost_usd:
          type: number
          minimum: 0
        reserved_cost_usd:
          type: number
          minimum: 0
        provider_disclosed:
          type: boolean
          const: false
      additionalProperties: false
    ImageEditRequest:
      allOf:
      - $ref: '#/components/schemas/ImageGenerationRequest'
      - type: object
        required:
        - images
        properties:
          images:
            type: array
            minItems: 1
            items:
              type: object
              required:
              - image_url
              properties:
                image_url:
                  type: string
                  format: uri
                  description: Public HTTPS PNG/JPEG/WebP reference image fetched by the generation provider.
              additionalProperties: false
      description: JSON URL-based image editing using one or more public HTTPS reference images.
    VideoObject:
      type: object
      required:
      - id
      - task_id
      - object
      - model
      - status
      properties:
        id:
          type: string
          description: Infer-owned task id.
        task_id:
          type: string
          description: Same Infer-owned task id; upstream task ids remain private.
        object:
          type: string
          const: video
        model:
          type: string
        status:
          type: string
          enum:
          - queued
          - pending
          - processing
          - in_progress
          - completed
          - failed
        progress: {}
        metadata:
          type: object
          properties:
            url:
              type: string
              format: uri
              description: Authenticated Infer content endpoint after completion.
          additionalProperties: false
        relay:
          $ref: '#/components/schemas/GenerationRelayMetadata'
      additionalProperties: false
    ImageGenerationRequest:
      type: object
      required:
      - model
      - prompt
      properties:
        model:
          type: string
          description: gpt-image-2 or infer/gpt-image-2:stable. Native image generation is currently Stable-only.
        prompt:
          type: string
          minLength: 1
          maxLength: 32000
        n:
          type: integer
          const: 1
          default: 1
        quality:
          type: string
          enum:
          - medium
          - high
          default: medium
        size:
          type: string
          pattern: ^[0-9]+x[0-9]+$
          default: 1024x1024
          description: Must match a currently priced GPT Image 2 size in /api/public/catalog.
        response_format:
          type: string
          enum:
          - url
          - b64_json
          default: url
        output_format:
          type: string
          const: png
          default: png
        stream:
          type: boolean
          const: false
          default: false
          description: Image SSE is not currently exposed by Infer.
        idempotency_key:
          type: string
          maxLength: 200
      additionalProperties: false
    VideoCreateRequest:
      type: object
      required:
      - model
      - prompt
      - duration
      - resolution
      properties:
        model:
          type: string
          description: seedance-2.0 / seedance-2.5, optionally using infer/<model>:stable.
        prompt:
          type: string
          minLength: 1
          maxLength: 32000
        duration:
          type: integer
          minimum: 4
          description: Generated seconds. Seedance 2.0 is capped at 15 seconds; 2.5 at 30 seconds.
        seconds:
          type: integer
          minimum: 4
          description: Alias for duration.
        resolution:
          type: string
          enum:
          - 480p
          - 720p
        image:
          type: string
          format: uri
          description: Optional public HTTPS reference image for image-to-video.
        idempotency_key:
          type: string
          maxLength: 200
      additionalProperties: false
    OpenAICompatErrorEnvelope:
      type: object
      required:
      - error
      - request_id
      properties:
        error:
          type: object
          required:
          - message
          - type
          - param
          - code
          properties:
            message:
              type: string
            type:
              type: string
            param:
              type:
              - string
              - 'null'
            code:
              type:
              - string
              - 'null'
          additionalProperties: false
        request_id:
          type: string
      additionalProperties: false
    ImageGenerationResponse:
      type: object
      required:
      - created
      - data
      properties:
        created:
          type: integer
        data:
          type: array
          minItems: 1
          maxItems: 1
          items:
            type: object
            properties:
              url:
                type: string
                format: uri
                description: Short-lived Infer-signed content URL. Supplier URLs are never returned.
              b64_json:
                type: string
                description: PNG base64 when response_format=b64_json. Infer does not retain the generated bytes.
            additionalProperties: false
        relay:
          $ref: '#/components/schemas/GenerationRelayMetadata'
      additionalProperties: false
  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)