> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aixy-gateway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a model response

> Create an OpenAI-compatible response through the same project policies and provider routing. Matching native requests pass through; other models use explicit translation. Streaming events are forwarded incrementally. Translated routes support stateless conversations and function tools; stored conversation state, hosted tools and unsupported advanced fields are rejected.



## OpenAPI

````yaml /openapi.json post /v1/responses
openapi: 3.1.0
info:
  title: Aixy Inference API
  version: 0.1.0
  description: >-
    Route requests to configured AI providers through OpenAI- and
    Anthropic-compatible APIs. Aixy applies project access, model policies,
    guardrails, routing, budgets, and usage attribution before forwarding
    inference traffic. Create connections, API keys and policies in the Aixy
    dashboard. The management API is a dashboard service and is not a public
    integration contract. Native provider features depend on the selected model
    and connection; translated requests support the documented conversation and
    function-tool subset. Unsupported combinations return explicit errors.
    Examples use illustrative model IDs; select an ID available to your project.
servers:
  - url: https://api.aixy-gateway.com
    description: Aixy production gateway
security: []
tags:
  - name: OpenAI
    description: OpenAI-compatible conversations, function tools and incremental streams.
  - name: Anthropic
    description: Anthropic-compatible messages and provider-native input token counting.
  - name: Decisions
    description: Typed, non-streaming classification and scoring inference.
  - name: Models
    description: Discover the models available to your project API key.
paths:
  /v1/responses:
    post:
      tags:
        - OpenAI
      summary: Create a model response
      description: >-
        Create an OpenAI-compatible response through the same project policies
        and provider routing. Matching native requests pass through; other
        models use explicit translation. Streaming events are forwarded
        incrementally. Translated routes support stateless conversations and
        function tools; stored conversation state, hosted tools and unsupported
        advanced fields are rejected.
      operationId: create_response
      parameters:
        - $ref: '#/components/parameters/XRequestId'
        - $ref: '#/components/parameters/XAixyClient'
        - $ref: '#/components/parameters/XAixySession'
        - $ref: '#/components/parameters/XAixySessionId'
        - $ref: '#/components/parameters/XProvider'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesRequest'
            examples:
              basic:
                summary: Basic request
                value:
                  model: openai/gpt-4.1-mini
                  input: Summarize the benefits of an AI gateway.
                  max_output_tokens: 256
                  stream: false
              functionTools:
                summary: Function tools (executed by your application)
                value:
                  model: openai/gpt-4.1-mini
                  input: What is the weather in Paris?
                  max_output_tokens: 256
                  stream: false
                  tools:
                    - type: function
                      name: get_weather
                      description: Read the weather for a city.
                      parameters:
                        type: object
                        properties:
                          city:
                            type: string
                        required:
                          - city
                        additionalProperties: false
              streaming:
                summary: Incremental stream
                value:
                  model: openai/gpt-4.1-mini
                  input: Summarize the benefits of an AI gateway.
                  max_output_tokens: 256
                  stream: true
      responses:
        '200':
          description: Successful response or server-sent event stream.
          headers:
            x-request-id:
              description: >-
                Aixy request identifier for correlation with Activity and
                support.
              schema:
                type: string
              example: req_example_01
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
              example:
                id: resp_example
                object: response
                status: completed
                model: openai/gpt-4.1-mini
                output:
                  - id: msg_example
                    type: message
                    role: assistant
                    status: completed
                    content:
                      - type: output_text
                        text: Hello.
                        annotations: []
                usage:
                  input_tokens: 8
                  output_tokens: 2
                  total_tokens: 10
            text/event-stream:
              schema:
                type: string
                description: >-
                  Representative SSE frames. Parse complete events across
                  network chunks. Chat Completions ends with data: [DONE];
                  Responses uses typed response events. Native provider events
                  and error events are preserved. Usage may arrive only near
                  completion.
              example: >+
                event: response.output_text.delta

                data:
                {"type":"response.output_text.delta","item_id":"msg_example","output_index":0,"content_index":0,"delta":"Hello","sequence_number":1}

        '400':
          $ref: '#/components/responses/GatewayError'
        '401':
          $ref: '#/components/responses/GatewayError'
        '403':
          $ref: '#/components/responses/GatewayError'
        '404':
          $ref: '#/components/responses/GatewayError'
        '408':
          $ref: '#/components/responses/GatewayError'
        '413':
          $ref: '#/components/responses/GatewayError'
        '424':
          $ref: '#/components/responses/GatewayError'
        '429':
          $ref: '#/components/responses/OpenAIRateLimitError'
        '500':
          $ref: '#/components/responses/InferenceInternalError'
        '502':
          $ref: '#/components/responses/GatewayError'
        '503':
          $ref: '#/components/responses/GatewayError'
        '504':
          $ref: '#/components/responses/GatewayError'
        default:
          $ref: '#/components/responses/NativeProviderError'
      security:
        - GatewayApiKey: []
components:
  parameters:
    XRequestId:
      name: X-Request-ID
      in: header
      required: false
      description: Optional caller-generated request identifier for end-to-end tracing.
      schema:
        type: string
        maxLength: 255
    XAixyClient:
      name: X-Aixy-Client
      in: header
      required: false
      description: >-
        Optional application[/version] for Activity attribution. Overrides
        User-Agent detection. Use a product name, not personal data or
        credentials. Names are 1-64 ASCII letters, digits, spaces, dots,
        underscores or hyphens, starting with a letter or digit. Optional
        versions start with a digit and use up to 32 letters, digits, dots,
        underscores, plus signs or hyphens. Invalid values are ignored. This
        self-declared label grants no permissions and is not forwarded.
      schema:
        type: string
        maxLength: 97
        example: Acme Support/1.2.3
    XAixySession:
      name: X-Aixy-Session
      in: header
      required: false
      description: >-
        Optional opaque session identifier for virtual routes with session
        affinity. Scoped to the authenticated caller and alias; never forwarded
        or recorded. Send full conversation history. Invalid values return 400
        when affinity is enabled. Omission retains the route's normal strategy.
      schema:
        type: string
        minLength: 1
        maxLength: 128
        pattern: ^[A-Za-z0-9._:-]+$
        example: conversation-82
    XAixySessionId:
      name: X-Aixy-Session-ID
      in: header
      required: false
      description: >-
        Optional opaque conversation identifier recorded in Activity metadata.
        Reuse it for every call in a conversation. Sessions are isolated by
        organization, project, user and API key. Use no personal data or
        secrets. Invalid values are ignored. The header is not forwarded, grants
        no permissions and does not change routing affinity.
      schema:
        type: string
        minLength: 1
        maxLength: 128
        pattern: ^[A-Za-z0-9._:-]+$
        example: conversation-82
    XProvider:
      name: X-Provider
      in: header
      required: false
      description: >-
        Select a configured provider without changing an unqualified model
        identifier. A provider-qualified model is preferred for new
        integrations.
      schema:
        type: string
  schemas:
    ResponsesRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: Provider-qualified or Aixy routing model identifier.
          example: openai/gpt-4.1-mini
        input:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ResponseInputItem'
        instructions:
          type: string
        stream:
          type: boolean
          default: false
        temperature:
          type: number
        top_p:
          type: number
        max_output_tokens:
          type: integer
          minimum: 1
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ResponseTool'
        tool_choice:
          oneOf:
            - type: string
              enum:
                - none
                - auto
                - required
            - type: object
              additionalProperties: true
        parallel_tool_calls:
          type: boolean
        reasoning:
          type:
            - object
            - 'null'
          properties:
            effort:
              type:
                - string
                - 'null'
              enum:
                - auto
                - none
                - minimal
                - low
                - medium
                - high
                - xhigh
                - max
                - null
              description: >-
                Requested reasoning effort. Supported values depend on the
                destination model.
          additionalProperties: true
          description: >-
            Only effort is translated; other settings require native Responses
            support.
        text:
          type: object
          properties:
            format:
              type: object
              additionalProperties: true
          additionalProperties: true
          description: >-
            Responses output format; JSON Schema support depends on the
            destination.
        store:
          type: boolean
          default: false
          description: Stored provider state requires a native Responses route.
        background:
          type: boolean
          default: false
          description: Background execution requires a native Responses route.
        previous_response_id:
          type:
            - string
            - 'null'
          description: Provider continuation requires a native Responses route.
        conversation:
          type:
            - string
            - object
            - 'null'
          description: Stored conversation state requires a native Responses route.
          additionalProperties: true
        truncation:
          type: string
          enum:
            - disabled
            - auto
          description: >-
            Translated requests require disabled; automatic truncation requires
            native support.
      additionalProperties: true
    ResponseObject:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: response
        model:
          type: string
        status:
          type: string
        output:
          type: array
          items:
            type: object
            additionalProperties: true
        usage:
          type:
            - object
            - 'null'
          properties:
            input_tokens:
              type: integer
              minimum: 0
            output_tokens:
              type: integer
              minimum: 0
            total_tokens:
              type: integer
              minimum: 0
          additionalProperties: true
      additionalProperties: true
    ResponseInputItem:
      type: object
      description: >-
        Conversation message, function_call or function_call_output. Other item
        types require native support. Send the complete conversation on
        translated routes.
      properties:
        type:
          type: string
          example: message
        role:
          type: string
          enum:
            - developer
            - system
            - user
            - assistant
        content:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                additionalProperties: true
        call_id:
          type: string
        name:
          type: string
        arguments:
          type: string
          description: JSON-encoded function-call arguments.
        output:
          type: string
          description: Application-supplied result for function_call_output.
        id:
          type: string
        status:
          type: string
      additionalProperties: true
    ResponseTool:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          example: function
        name:
          type: string
          description: Function name returned to your application.
        description:
          type: string
        parameters:
          type: object
          additionalProperties: true
          description: JSON Schema for arguments. Your application executes the function.
        strict:
          type:
            - boolean
            - 'null'
      description: >-
        Function tools work on supported translations; hosted tools require a
        native Responses route.
      additionalProperties: true
    InferenceErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
          properties:
            message:
              type: string
            code:
              type:
                - string
                - 'null'
            type:
              type:
                - string
                - 'null'
            param:
              type:
                - string
                - integer
                - 'null'
            details:
              type:
                - object
                - 'null'
              additionalProperties: true
          additionalProperties: true
        type:
          type: string
        request_id:
          type: string
      additionalProperties: true
    AnthropicErrorResponse:
      type: object
      required:
        - type
        - error
      properties:
        type:
          type: string
          enum:
            - error
        error:
          type: object
          required:
            - type
            - message
          properties:
            type:
              type: string
            message:
              type: string
          additionalProperties: true
        request_id:
          type: string
      additionalProperties: true
  responses:
    GatewayError:
      description: >-
        The gateway or upstream provider rejected the request. Gateway codes
        identify invalid_request or unsupported_feature (400),
        invalid_gateway_api_key (401), access or policy denials (403),
        unavailable models (404), request deadlines (408/504), body limits
        (413), hard-budget admission failures (424), and upstream or gateway
        availability failures (502/503). Native provider error details may
        differ.
      headers:
        x-request-id:
          description: Aixy request identifier for correlation with Activity and support.
          schema:
            type: string
          example: req_example_01
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InferenceErrorResponse'
          example:
            error:
              code: invalid_gateway_api_key
              message: Gateway API key is invalid or revoked
    OpenAIRateLimitError:
      description: >-
        Aixy or the OpenAI-compatible provider rejected the request because of a
        rate limit.
      headers:
        x-request-id:
          description: Aixy request identifier for correlation with Activity and support.
          schema:
            type: string
          example: req_example_01
        Retry-After:
          description: >-
            Optional retry delay. Aixy rate-limit rejections provide a positive
            delay in seconds; a provider may supply its own Retry-After value,
            including an HTTP date.
          required: false
          schema:
            type: string
          example: '60'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InferenceErrorResponse'
          example:
            error:
              code: gateway_rate_limit_exceeded
              message: The configured rate limit was reached. Retry later.
    InferenceInternalError:
      description: >-
        An internal failure occurred. Some failures return a generic text
        response; record x-request-id and avoid relying on a JSON body for every
        server error.
      headers:
        x-request-id:
          description: Aixy request identifier for correlation with Activity and support.
          schema:
            type: string
          example: req_example_01
      content:
        text/plain:
          schema:
            type: string
          example: Internal Server Error
        application/json:
          schema:
            anyOf:
              - $ref: '#/components/schemas/InferenceErrorResponse'
              - $ref: '#/components/schemas/AnthropicErrorResponse'
    NativeProviderError:
      description: >-
        A native provider may return another error status and its original
        payload. After streaming starts, failures can arrive inside the SSE
        stream instead of changing the HTTP status. Handle both HTTP errors and
        protocol error events.
      headers:
        x-request-id:
          description: Aixy request identifier for correlation with Activity and support.
          schema:
            type: string
          example: req_example_01
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
  securitySchemes:
    GatewayApiKey:
      type: http
      scheme: bearer
      bearerFormat: gak_…
      description: >-
        A project-scoped Aixy API key. Create keys in the dashboard and send the
        secret as a Bearer token.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.