> ## 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

> 根据文本、图像或文件输入创建模型响应，支持结构化输出、工具调用、对话状态、后台处理和流式响应。

<Note>
  请求参数和响应字段与官方 Responses API 格式保持一致。完整规范请参考
  <a href="https://developers.openai.com/api/reference/resources/responses/methods/create" target="_blank">OpenAI 官方文档</a>。
</Note>

此接口支持文本、图像和文件输入，以及结构化输出、工具调用、多轮对话、后台处理和流式响应。


## OpenAPI

````yaml openapi/cn/llm.json POST /v1/responses
openapi: 3.1.0
info:
  title: LLM API DOCS
  version: 1.0.0
  description: TTAPI LLM API 接口服务。
servers:
  - url: https://api.ttapi.io
security: []
paths:
  /v1/responses:
    post:
      summary: 创建模型响应
      description: 根据文本、图像或文件输入创建模型响应，支持结构化输出、工具调用、对话状态、后台处理和流式响应。
      operationId: createResponse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesRequest'
      responses:
        '200':
          description: 请求成功。stream 为 true 时返回服务器发送事件。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
            text/event-stream:
              schema:
                type: string
                description: Responses API 的服务器发送事件流。
        '400':
          $ref: '#/components/responses/400Response'
        '401':
          $ref: '#/components/responses/401Response'
      security:
        - Authorization: []
components:
  schemas:
    ResponsesRequest:
      type: object
      description: OpenAI 兼容 Responses API 的请求体。
      properties:
        model:
          type: string
          example: gpt-5.4-mini
          description: 用于生成响应的模型 ID，详见[支持模型](/grids/cn/start/pricing/llm)。
        input:
          description: 发送给模型的文本、图像或文件输入；字符串会被视为用户消息。
          oneOf:
            - type: string
              example: 请用通俗语言解释量子计算。
            - type: array
              items:
                $ref: '#/components/schemas/ResponseInputItem'
        instructions:
          type: string
          description: 插入模型上下文的 system 或 developer 指令。使用 previous_response_id 时不会继承上一响应的指令。
        previous_response_id:
          type: string
          description: 上一条响应的 ID，用于多轮对话；不能与 conversation 同时使用。
        conversation:
          description: 此响应所属的对话。
          oneOf:
            - type: string
            - type: object
              properties:
                id:
                  type: string
              required:
                - id
        background:
          type: boolean
          default: false
          description: 是否在后台运行响应。
        include:
          type: array
          description: 指定响应中需要额外包含的输出数据。
          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: 可生成的最大 token 数，包括可见输出和推理 token。
        max_tool_calls:
          type: integer
          minimum: 1
          description: 本次响应可处理的内置工具调用总数上限。
        metadata:
          type: object
          maxProperties: 16
          additionalProperties:
            type: string
            maxLength: 512
          description: 附加到响应的最多 16 个字符串键值对。
        parallel_tool_calls:
          type: boolean
          default: true
          description: 是否允许模型并行调用工具。
        prompt:
          type: object
          description: 可复用提示词模板及变量。
          properties:
            id:
              type: string
            version:
              type: string
            variables:
              type: object
              additionalProperties: true
          required:
            - id
        prompt_cache_key:
          type: string
          description: 用于提高提示词缓存命中率的稳定键。
        prompt_cache_retention:
          type: string
          enum:
            - in-memory
            - 24h
          description: 提示词缓存保留策略。
        reasoning:
          type: object
          description: 受支持模型的推理配置。
          properties:
            effort:
              type: string
              enum:
                - none
                - minimal
                - low
                - medium
                - high
                - xhigh
            summary:
              type: string
              enum:
                - auto
                - concise
                - detailed
        safety_identifier:
          type: string
          description: 用于滥用检测的稳定终端用户标识。
        service_tier:
          type: string
          enum:
            - auto
            - default
            - flex
            - scale
            - priority
        store:
          type: boolean
          description: 是否存储生成的响应，以便后续通过 API 获取。
        stream:
          type: boolean
          default: false
          description: 是否通过服务器发送事件（SSE）流式返回响应。
        stream_options:
          type: object
          description: 流式响应选项，仅在 stream 为 true 时设置。
          properties:
            include_obfuscation:
              type: boolean
              default: true
        temperature:
          type: number
          minimum: 0
          maximum: 2
          description: 采样温度。通常只调整 temperature 或 top_p 其中之一。
        text:
          $ref: '#/components/schemas/ResponseTextConfig'
        tool_choice:
          description: 控制模型可调用哪些工具。
          oneOf:
            - type: string
              enum:
                - none
                - auto
                - required
            - type: object
              additionalProperties: true
        tools:
          type: array
          description: 提供给模型的函数工具或受支持的内置工具。
          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 提供的聚合文本输出便捷字段。
        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: 输入消息、工具输出或引用项。
      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: 工具调用返回的输出。
      additionalProperties: true
    ResponseTextConfig:
      type: object
      properties:
        format:
          type: object
          description: 纯文本、JSON 对象或 JSON Schema 输出格式。
          additionalProperties: true
        verbosity:
          type: string
          enum:
            - low
            - medium
            - high
    ResponseOutputItem:
      type: object
      description: 消息、推理项、工具调用或其他响应输出项。
      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: 参数错误
      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: 授权失败
      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: >-
        请前往 <a href='https://dashboard.ttapi.io' target='_blank'>TTAPI 控制台</a>
        获取 API 密钥。

````