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

# Direct Responses

> Generate Responses API outputs directly from the selected model without Gloo governance.

<Card title="Error Reference: Responses" icon="triangle-exclamation" href="/api-reference/general/errors">
  Common errors: unsupported model, unsupported sampling parameter, context window exceeded, provider timeout, provider unavailable.
</Card>


## OpenAPI

````yaml post /ai/v2/direct/responses
openapi: 3.1.0
info:
  title: AI API
  description: |-
    Optimized for high-speed inference and scalability by Gloo AI

    [Swagger UI](./docs) | [ReDoc UI](./redoc)
  version: 1.0.0
servers:
  - url: https://platform.ai.gloo.com
security:
  - bearerAuth: []
tags:
  - name: Content Controls
  - name: Data Engine
  - name: Ingestion & Enrichment
  - name: answers
  - name: chat
  - name: completions
  - name: content
  - name: core
  - name: data
  - name: get-models
  - name: ingestion
  - name: sotc
paths:
  /ai/v2/direct/responses:
    post:
      tags:
        - v2
      summary: Direct Responses API (v2)
      description: >-
        Generate Responses API outputs directly from the selected model without
        Gloo governance.
      operationId: post-v2-direct-responses
      parameters:
        - in: header
          name: X-Cache-TTL
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Cache-Ttl
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3Request'
        required: true
      responses:
        '200':
          description: >-
            Successful Responses API result. If `stream` is false or omitted,
            the response is JSON. If `stream=true`, the response is a named
            Server-Sent Events stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsesApiResponse'
            text/event-stream:
              schema:
                description: >-
                  JSON payloads sent in named Server-Sent Events. The event name
                  is provided in the preceding `event:` line.
                anyOf:
                  - $ref: '#/components/schemas/ResponsesStreamOutputItemEvent'
                  - $ref: '#/components/schemas/ResponsesStreamContentPartEvent'
                  - $ref: '#/components/schemas/ResponsesStreamTextDeltaEvent'
                  - $ref: >-
                      #/components/schemas/ResponsesStreamFunctionArgumentsDeltaEvent
                  - $ref: '#/components/schemas/ResponsesStreamCompletedEvent'
              x-event-payload-schemas:
                - '#/components/schemas/ResponsesStreamOutputItemEvent'
                - '#/components/schemas/ResponsesStreamContentPartEvent'
                - '#/components/schemas/ResponsesStreamTextDeltaEvent'
                - >-
                  #/components/schemas/ResponsesStreamFunctionArgumentsDeltaEvent
                - '#/components/schemas/ResponsesStreamCompletedEvent'
              examples:
                text_delta:
                  summary: response.output_text.delta event payload
                  value:
                    delta: Hello
                    output_index: 0
                    content_index: 0
                completed:
                  summary: response.completed event payload
                  value:
                    id: resp_123
                    object: response
                    status: completed
                    usage:
                      input_tokens: 8
                      output_tokens: 7
                      total_tokens: 15
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    V3Request:
      additionalProperties: true
      description: Request body for the Responses API (`POST /ai/v2/direct/responses`).
      properties:
        frequency_penalty:
          anyOf:
            - type: number
            - type: 'null'
          title: Frequency Penalty
        image_generation:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            Image generation options (quality, size) mapped onto OpenAI's
            image_generation tool; ignored by providers without quality
            controls.
          title: Image Generation
        input:
          anyOf:
            - type: string
            - items:
                additionalProperties: true
                type: object
              type: array
          description: String prompt or array of input items
          title: Input
        instructions:
          anyOf:
            - type: string
            - type: 'null'
          title: Instructions
        max_output_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Output Tokens
        model:
          title: Model
          type: string
        parallel_tool_calls:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Parallel Tool Calls
        presence_penalty:
          anyOf:
            - type: number
            - type: 'null'
          title: Presence Penalty
        prompt_cache_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt Cache Key
        reasoning:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Reasoning
        response_format:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Response Format
        stop:
          anyOf:
            - {}
            - type: 'null'
          title: Stop
        stream:
          default: false
          title: Stream
          type: boolean
        temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Temperature
        tool_choice:
          anyOf:
            - {}
            - type: 'null'
          title: Tool Choice
        tools:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Tools
        top_p:
          anyOf:
            - type: number
            - type: 'null'
          title: Top P
      required:
        - model
        - input
      title: V3Request
      type: object
    ResponsesApiResponse:
      type: object
      title: Responses API Response
      description: A non-streaming Responses API result.
      additionalProperties: true
      properties:
        id:
          type: string
        object:
          type: string
          const: response
          default: response
        created_at:
          type: integer
          description: Unix timestamp when the response was created.
        model:
          type: string
        status:
          type: string
          enum:
            - completed
            - failed
            - in_progress
            - incomplete
        output:
          type: array
          description: >-
            Items generated by the model, such as assistant messages, images,
            function calls, or reasoning summaries.
          items:
            $ref: '#/components/schemas/ResponsesOutputItem'
        usage:
          $ref: '#/components/schemas/ResponsesUsage'
        instructions:
          type: string
        max_output_tokens:
          type: integer
        metadata:
          type: object
          additionalProperties:
            type: string
        parallel_tool_calls:
          type: boolean
        prompt_cache_key:
          type: string
        reasoning:
          additionalProperties: true
          type: object
        temperature:
          type: number
        text:
          additionalProperties: true
          type: object
        tool_choice: {}
        tools:
          items:
            additionalProperties: true
            type: object
          type: array
        top_p:
          type: number
        ignored_params:
          $ref: '#/components/schemas/ResponsesIgnoredParams'
      required:
        - id
        - object
        - created_at
        - model
        - status
        - output
      example:
        id: resp_123
        object: response
        created_at: 1716912000
        model: gloo-openai-gpt-5.5
        status: completed
        output:
          - type: message
            id: msg_123
            role: assistant
            status: completed
            content:
              - type: output_text
                text: Hello! How can I help?
        usage:
          input_tokens: 8
          output_tokens: 7
          total_tokens: 15
    ResponsesStreamOutputItemEvent:
      type: object
      title: Output Item Event
      description: >-
        The JSON payload in a `response.output_item.added` or
        `response.output_item.done` SSE event.
      additionalProperties: true
      properties:
        type:
          type: string
          enum:
            - message
            - function_call
            - image_generation_call
        id:
          type: string
        status:
          type: string
        output_index:
          type: integer
        role:
          type: string
        content:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/ResponsesOutputText'
              - $ref: '#/components/schemas/ResponsesOutputRefusal'
        call_id:
          type: string
        name:
          type: string
        arguments:
          type: string
        result:
          type: string
      required:
        - type
        - id
    ResponsesStreamContentPartEvent:
      type: object
      title: Content Part Event
      description: >-
        The JSON payload in a `response.content_part.added` or
        `response.content_part.done` SSE event.
      properties:
        type:
          type: string
          const: output_text
          default: output_text
        text:
          type: string
        output_index:
          type: integer
        content_index:
          type: integer
      required:
        - type
        - text
        - output_index
        - content_index
    ResponsesStreamTextDeltaEvent:
      type: object
      title: Text Delta Event
      description: The JSON payload in a `response.output_text.delta` SSE event.
      properties:
        delta:
          type: string
        output_index:
          type: integer
        content_index:
          type: integer
      required:
        - delta
        - output_index
        - content_index
    ResponsesStreamFunctionArgumentsDeltaEvent:
      type: object
      title: Function Call Arguments Event
      description: >-
        The JSON payload in a `response.function_call_arguments.delta` SSE
        event.
      properties:
        delta:
          type: string
        output_index:
          type: integer
      required:
        - delta
        - output_index
    ResponsesStreamCompletedEvent:
      type: object
      title: Completion Event
      description: The JSON payload in the terminal `response.completed` SSE event.
      additionalProperties: true
      properties:
        id:
          type: string
        object:
          type: string
          const: response
          default: response
        status:
          type: string
          const: completed
          default: completed
        usage:
          $ref: '#/components/schemas/ResponsesUsage'
      required:
        - id
        - object
        - status
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ResponsesOutputItem:
      title: Output Item
      description: >-
        An item generated by the model. An item can be an assistant message,
        generated image, function call, or reasoning summary.
      oneOf:
        - $ref: '#/components/schemas/ResponsesOutputMessage'
        - $ref: '#/components/schemas/ResponsesImageGenerationCall'
        - $ref: '#/components/schemas/ResponsesFunctionCall'
        - $ref: '#/components/schemas/ResponsesReasoning'
    ResponsesUsage:
      type: object
      title: Usage
      description: Token usage for the response.
      properties:
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        total_tokens:
          type: integer
        input_tokens_details:
          type: object
          properties:
            cached_tokens:
              type: integer
        output_tokens_details:
          type: object
          properties:
            reasoning_tokens:
              type: integer
        server_tool_use:
          type: object
          properties:
            web_search_requests:
              type: integer
      required:
        - input_tokens
        - output_tokens
        - total_tokens
    ResponsesIgnoredParams:
      type: object
      title: Ignored Parameters
      description: >-
        Sampling parameters ignored because the selected model does not support
        them.
      properties:
        params:
          type: array
          items:
            type: string
        model:
          type: string
        reason:
          type: string
      required:
        - params
        - model
        - reason
    ResponsesOutputText:
      type: object
      title: Text
      description: Text generated by the model, optionally with source citations.
      properties:
        type:
          type: string
          const: output_text
          default: output_text
        text:
          type: string
          description: The generated text.
        annotations:
          type: array
          description: Source citations associated with the generated text.
          items:
            $ref: '#/components/schemas/ResponsesUrlCitation'
      required:
        - type
        - text
    ResponsesOutputRefusal:
      type: object
      title: Refusal
      description: A refusal returned instead of generated text.
      properties:
        type:
          type: string
          const: refusal
          default: refusal
        refusal:
          type: string
          description: The refusal message.
      required:
        - type
        - refusal
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ResponsesOutputMessage:
      type: object
      title: Message
      description: An assistant message produced by the model.
      properties:
        type:
          type: string
          const: message
          default: message
        id:
          type: string
          description: Unique identifier for the message.
        role:
          type: string
          const: assistant
          default: assistant
        status:
          type: string
          description: Processing status of the message.
          enum:
            - completed
            - in_progress
            - failed
        content:
          type: array
          description: >-
            Content parts in the assistant message. Each part contains generated
            text or a refusal.
          items:
            oneOf:
              - $ref: '#/components/schemas/ResponsesOutputText'
              - $ref: '#/components/schemas/ResponsesOutputRefusal'
      required:
        - type
        - id
        - role
        - status
        - content
    ResponsesImageGenerationCall:
      type: object
      title: Image Generation
      description: An image generated by the model.
      properties:
        type:
          type: string
          const: image_generation_call
          default: image_generation_call
        id:
          type: string
          description: Unique identifier for the image generation item.
        status:
          type: string
          description: Processing status of the image generation request.
          enum:
            - completed
            - in_progress
            - generating
            - failed
        result:
          type: string
          description: Base64-encoded generated image data.
      required:
        - type
        - id
        - status
    ResponsesFunctionCall:
      type: object
      title: Function Call
      description: A function call requested by the model.
      properties:
        type:
          type: string
          const: function_call
          default: function_call
        id:
          type: string
          description: Unique identifier for the function call output item.
        call_id:
          type: string
          description: Identifier used to associate the function result with this call.
        name:
          type: string
          description: Name of the function to call.
        arguments:
          type: string
          description: JSON-encoded function arguments.
      required:
        - type
        - id
        - call_id
        - name
        - arguments
    ResponsesReasoning:
      type: object
      title: Reasoning
      description: A reasoning summary produced by a reasoning model.
      properties:
        type:
          type: string
          const: reasoning
          default: reasoning
        id:
          type: string
          description: Unique identifier for the reasoning item.
        summary:
          type: array
          description: Summary parts describing the model's reasoning.
          items:
            type: object
            additionalProperties:
              type: string
      required:
        - type
        - id
        - summary
    ResponsesUrlCitation:
      type: object
      title: URL Citation
      description: A source citation attached to an output text part.
      properties:
        type:
          type: string
          const: url_citation
          default: url_citation
        url:
          type: string
        title:
          type: string
        start_index:
          type: integer
        end_index:
          type: integer
      required:
        - type
        - url
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: api-key
      x-default: <api-key>
      description: >-
        Bearer authentication header of the form Bearer `<api-key>`, where
        `<api-key>` is your [API key](/studio/manage-api-credentials).

````