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

# Responses

> Creates a model response from text, image, or file input. Supports structured output, tool calls, conversation state, background processing, and streaming.

<Note>
  The request and response fields follow the official Responses API format. See the
  <a href="https://developers.openai.com/api/reference/resources/responses/methods/create" target="_blank">OpenAI API reference</a>
  for the complete specification.
</Note>

Use this endpoint for text, image, and file inputs, structured outputs, tool calls,
multi-turn conversations, background processing, and streaming responses.


## OpenAPI

````yaml openapi/en/llm.json POST /v1/responses
openapi: 3.1.0
info:
  title: LLM API DOCS
  version: 1.0.0
  description: TTAPI LLM API service.
servers:
  - url: https://api.ttapi.io
security: []
paths:
  /v1/responses:
    post:
      summary: Create a model response
      description: >-
        Creates a model response from text, image, or file input. Supports
        structured output, tool calls, conversation state, background
        processing, and streaming.
      operationId: createResponse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesRequest'
      responses:
        '200':
          description: >-
            Successful response. When stream is true, the endpoint returns
            server-sent events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
            text/event-stream:
              schema:
                type: string
                description: Responses API server-sent event stream.
        '400':
          $ref: '#/components/responses/400Response'
        '401':
          $ref: '#/components/responses/401Response'
      security:
        - Authorization: []
components:
  schemas:
    ResponsesRequest:
      type: object
      description: Request body for the OpenAI-compatible Responses API.
      properties:
        model:
          type: string
          example: gpt-5.4-mini
          description: >-
            Model ID used to generate the response. See [Supported
            Models](/grids/en/start/pricing/llm).
        input:
          description: >-
            Text, image, or file input to the model. A string is treated as a
            user message.
          oneOf:
            - type: string
              example: Explain quantum computing in simple terms.
            - type: array
              items:
                $ref: '#/components/schemas/ResponseInputItem'
        instructions:
          type: string
          description: >-
            A system or developer message inserted into the model context. It is
            not carried over when previous_response_id is used.
        previous_response_id:
          type: string
          description: >-
            ID of the previous response for multi-turn interactions. Cannot be
            used together with conversation.
        conversation:
          description: Conversation that this response belongs to.
          oneOf:
            - type: string
            - type: object
              properties:
                id:
                  type: string
              required:
                - id
        background:
          type: boolean
          default: false
          description: Whether to run the response in the background.
        include:
          type: array
          description: Additional output data to include in the response.
          items:
            type: string
            enum:
              - file_search_call.results
              - web_search_call.results
              - web_search_call.action.sources
              - message.input_image.image_url
              - computer_call_output.output.image_url
              - code_interpreter_call.outputs
              - reasoning.encrypted_content
              - message.output_text.logprobs
        max_output_tokens:
          type: integer
          minimum: 1
          description: >-
            Maximum number of generated tokens, including visible output and
            reasoning tokens.
        max_tool_calls:
          type: integer
          minimum: 1
          description: >-
            Maximum total number of built-in tool calls processed for this
            response.
        metadata:
          type: object
          maxProperties: 16
          additionalProperties:
            type: string
            maxLength: 512
          description: Up to 16 string key-value pairs attached to the response.
        parallel_tool_calls:
          type: boolean
          default: true
          description: Whether the model may call tools in parallel.
        prompt:
          type: object
          description: Reference to a reusable prompt template.
          properties:
            id:
              type: string
            version:
              type: string
            variables:
              type: object
              additionalProperties: true
          required:
            - id
        prompt_cache_key:
          type: string
          description: Stable key used to improve prompt cache hit rates.
        prompt_cache_retention:
          type: string
          enum:
            - in-memory
            - 24h
          description: Prompt cache retention policy.
        reasoning:
          type: object
          properties:
            effort:
              type: string
              enum:
                - none
                - minimal
                - low
                - medium
                - high
                - xhigh
            summary:
              type: string
              enum:
                - auto
                - concise
                - detailed
          description: Reasoning configuration for supported models.
        safety_identifier:
          type: string
          description: Stable identifier for the end user, used for abuse detection.
        service_tier:
          type: string
          enum:
            - auto
            - default
            - flex
            - scale
            - priority
        store:
          type: boolean
          description: Whether to store the generated response for later retrieval.
        stream:
          type: boolean
          default: false
          description: Whether to stream response events using server-sent events.
        stream_options:
          type: object
          properties:
            include_obfuscation:
              type: boolean
              default: true
          description: Streaming options. Set only when stream is true.
        temperature:
          type: number
          minimum: 0
          maximum: 2
          description: Sampling temperature. Change this or top_p, but generally not both.
        text:
          $ref: '#/components/schemas/ResponseTextConfig'
        tool_choice:
          description: Controls which tool or tools the model may call.
          oneOf:
            - type: string
              enum:
                - none
                - auto
                - required
            - type: object
              additionalProperties: true
        tools:
          type: array
          description: >-
            Tools available to the model, including function and supported
            built-in tools.
          items:
            type: object
            additionalProperties: true
        top_logprobs:
          type: integer
          minimum: 0
          maximum: 20
        top_p:
          type: number
          minimum: 0
          maximum: 1
        truncation:
          type: string
          enum:
            - auto
            - disabled
          default: disabled
    ResponseObject:
      type: object
      properties:
        id:
          type: string
          example: resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b
        object:
          type: string
          const: response
        created_at:
          type: number
          example: 1741476542
        status:
          type: string
          enum:
            - completed
            - failed
            - in_progress
            - cancelled
            - queued
            - incomplete
        error:
          oneOf:
            - type: object
              properties:
                code:
                  type: string
                message:
                  type: string
            - type: 'null'
        incomplete_details:
          oneOf:
            - type: object
              properties:
                reason:
                  type: string
                  enum:
                    - max_output_tokens
                    - content_filter
            - type: 'null'
        model:
          type: string
        output:
          type: array
          items:
            $ref: '#/components/schemas/ResponseOutputItem'
        output_text:
          type: string
          readOnly: true
          description: SDK convenience property containing aggregated text output.
        previous_response_id:
          type:
            - string
            - 'null'
        store:
          type: boolean
        usage:
          $ref: '#/components/schemas/ResponseUsage'
        metadata:
          type: object
          additionalProperties:
            type: string
      required:
        - id
        - object
        - created_at
        - status
        - model
        - output
    ResponseInputItem:
      type: object
      description: An input message, tool output, or reference item.
      properties:
        type:
          type: string
        role:
          type: string
          enum:
            - user
            - assistant
            - system
            - developer
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ResponseInputContent'
        id:
          type: string
        call_id:
          type: string
        output:
          description: Output returned by a tool call.
      additionalProperties: true
    ResponseTextConfig:
      type: object
      properties:
        format:
          type: object
          description: Text, JSON object, or JSON schema output format.
          additionalProperties: true
        verbosity:
          type: string
          enum:
            - low
            - medium
            - high
    ResponseOutputItem:
      type: object
      description: A message, reasoning item, tool call, or other response output item.
      properties:
        type:
          type: string
        id:
          type: string
        status:
          type: string
        role:
          type: string
          enum:
            - assistant
        content:
          type: array
          items:
            $ref: '#/components/schemas/ResponseOutputContent'
        call_id:
          type: string
        name:
          type: string
        arguments:
          type: string
      additionalProperties: true
    ResponseUsage:
      type: object
      properties:
        input_tokens:
          type: integer
        input_tokens_details:
          type: object
          properties:
            cached_tokens:
              type: integer
        output_tokens:
          type: integer
        output_tokens_details:
          type: object
          properties:
            reasoning_tokens:
              type: integer
        total_tokens:
          type: integer
    ResponseInputContent:
      type: object
      properties:
        type:
          type: string
          enum:
            - input_text
            - input_image
            - input_file
        text:
          type: string
        image_url:
          type: string
        file_id:
          type: string
        file_url:
          type: string
        file_data:
          type: string
        filename:
          type: string
        detail:
          type: string
          enum:
            - low
            - high
            - auto
      required:
        - type
    ResponseOutputContent:
      type: object
      properties:
        type:
          type: string
          enum:
            - output_text
            - refusal
        text:
          type: string
        refusal:
          type: string
        annotations:
          type: array
          items:
            type: object
            additionalProperties: true
        logprobs:
          type: array
          items:
            type: object
            additionalProperties: true
      required:
        - type
  responses:
    400Response:
      description: Parameter error
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: FAILED
              message:
                type: string
                example: '"prompt" cannot be empty.'
              data:
                type: object
            required:
              - status
              - message
    401Response:
      description: Authorization failed
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: FAILED
              message:
                type: string
                example: Wrong TT-API-KEY or email is not activated.
            required:
              - status
              - message
  securitySchemes:
    Authorization:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        You can obtain your API key from the <a
        href='https://dashboard.ttapi.io' target='_blank'>TTAPI Dashboard</a>.

````