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

# Responses API

> Creates a model response. Provide text or image inputs to generate text or JSON outputs. Have the model call the function tools you define.

<Accordion title="Examples">
  <CodeGroup>
    ```python Python theme={null}
    import os

    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ["MOONSHOT_API_KEY"],
        base_url="https://api.moonshot.ai/v1",
    )

    response = client.responses.create(
        model="kimi-k3",
        instructions="You are Kimi, an AI assistant provided by Moonshot AI.",
        input="Explain context caching in one sentence.",
    )

    print(response.output_text)
    ```

    ```javascript Node.js theme={null}
    import OpenAI from "openai";

    const client = new OpenAI({
        apiKey: process.env.MOONSHOT_API_KEY,
        baseURL: "https://api.moonshot.ai/v1",
    });

    const response = await client.responses.create({
        model: "kimi-k3",
        instructions: "You are Kimi, an AI assistant provided by Moonshot AI.",
        input: "Explain context caching in one sentence.",
    });

    console.log(response.output_text);
    ```

    ```bash cURL theme={null}
    curl https://api.moonshot.ai/v1/responses \
        --header "Content-Type: application/json" \
        --header "Authorization: Bearer $MOONSHOT_API_KEY" \
        --data '{
            "model": "kimi-k3",
            "instructions": "You are Kimi, an AI assistant provided by Moonshot AI.",
            "input": "Explain context caching in one sentence."
        }'
    ```
  </CodeGroup>
</Accordion>


## OpenAPI

````yaml POST /v1/responses
openapi: 3.1.0
info:
  title: Moonshot AI API
  version: 1.0.0
  description: API for Moonshot AI / Kimi large language model services
servers:
  - url: https://api.moonshot.ai
    description: Production
security: []
paths:
  /v1/responses:
    post:
      tags:
        - Responses
      summary: Create a model response
      description: >-
        Creates a model response. Provide text or image inputs to generate text
        or JSON outputs. Have the model call the function tools you define. When
        `stream` is `true`, the response is delivered as a stream of SSE events.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesRequest'
      responses:
        '200':
          description: The response was created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsesResponse'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ResponsesStreamEvent'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - the API key is invalid or missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access to the resource is forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limited or out of quota
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    ResponsesRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: ID of the model to use. This endpoint currently supports `kimi-k3`.
          example: kimi-k3
        input:
          description: >-
            Input for this request. A string is equivalent to a single user
            message. An array holds ordered typed items and may contain
            conversation history, tool calls, and tool results.
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ResponsesInputItem'
        instructions:
          type: string
          description: Top-level system instructions, applied ahead of every input item.
        stream:
          type: boolean
          default: false
          description: When true, the response is delivered as a stream of SSE events.
        max_output_tokens:
          type: integer
          description: >-
            Maximum number of tokens to generate for this response. For
            `kimi-k3` it defaults to 131072 and can be set up to 1048576. This
            refers to the length of tokens you expect us to return, not the
            total length of input plus output. When the limit is reached,
            `status` is `incomplete` and `incomplete_details.reason` is
            `max_output_tokens`.
        reasoning:
          type: object
          description: Reasoning configuration.
          properties:
            effort:
              type: string
              enum:
                - low
                - high
                - max
              default: max
              description: >-
                Reasoning depth. Higher levels reason more thoroughly, which
                usually also increases latency and reasoning token usage.
        text:
          type: object
          description: Output text configuration.
          properties:
            format:
              type: object
              required:
                - type
                - schema
              description: Constrains the output structure with a JSON Schema.
              properties:
                type:
                  type: string
                  enum:
                    - json_schema
                name:
                  type: string
                  description: Schema name. Defaults to `output`.
                schema:
                  type: object
                  description: JSON Schema describing the output structure.
                strict:
                  type: boolean
                  description: Whether the output must strictly conform to the schema.
        tools:
          type: array
          description: List of tools the model may call.
          items:
            $ref: '#/components/schemas/ResponsesTool'
        tool_choice:
          $ref: '#/components/schemas/ResponsesToolChoice'
        prompt_cache_key:
          type: string
          description: >-
            Context cache identifier. Reusing the same value across a session
            improves cache hit rate.
        safety_identifier:
          type: string
          description: >-
            A stable identifier used to help detect users of your application
            that may be violating usage policies. The ID should be a string that
            uniquely identifies each user. It is recommended to hash the
            username or email address to avoid sending any identifying
            information
    ResponsesResponse:
      type: object
      description: A single model response.
      properties:
        id:
          type: string
          description: Unique identifier of the response.
          example: resp_68f0c1c2d3e4f5a6b7c8d9e0
        object:
          type: string
          enum:
            - response
        created_at:
          type: integer
          description: Unix timestamp of when the response was created.
        completed_at:
          type:
            - integer
            - 'null'
          description: >-
            Unix timestamp of when the response finished. Present when `status`
            is `completed` or `incomplete`; `null` when `status` is
            `in_progress` or `failed`.
        status:
          type: string
          enum:
            - in_progress
            - completed
            - incomplete
            - failed
          description: Response status. The opening snapshot of a stream is `in_progress`.
        model:
          type: string
          description: Model that produced the response.
        output:
          type: array
          description: >-
            Array of output items, ordered as reasoning, message, then tool
            calls.
          items:
            $ref: '#/components/schemas/ResponsesOutputItem'
        usage:
          oneOf:
            - $ref: '#/components/schemas/ResponsesUsage'
            - type: 'null'
        incomplete_details:
          type:
            - object
            - 'null'
          description: Reason the response is `incomplete`.
          properties:
            reason:
              type: string
              enum:
                - max_output_tokens
                - content_filter
        error:
          type:
            - object
            - 'null'
          description: Error information when `status` is `failed`.
          properties:
            code:
              type: string
            message:
              type: string
        instructions:
          type:
            - string
            - 'null'
        reasoning:
          type:
            - object
            - 'null'
        text:
          type:
            - object
            - 'null'
        tools:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ResponsesTool'
        tool_choice:
          oneOf:
            - $ref: '#/components/schemas/ResponsesToolChoice'
            - type: 'null'
        max_output_tokens:
          type:
            - integer
            - 'null'
        temperature:
          type:
            - number
            - 'null'
        top_p:
          type:
            - number
            - 'null'
        metadata:
          type:
            - object
            - 'null'
        parallel_tool_calls:
          type: boolean
        service_tier:
          type:
            - string
            - 'null'
        store:
          type: boolean
          description: Always `false`.
        background:
          type:
            - boolean
            - 'null'
          description: Always `false`.
        previous_response_id:
          type:
            - string
            - 'null'
          description: Always `null`.
        conversation:
          type:
            - object
            - 'null'
          description: Always `null`.
    ResponsesStreamEvent:
      type: object
      description: >-
        A single SSE event returned when `stream: true`. Each frame is `event:
        <type>` followed by `data: <json>`, and the remaining fields of the
        event body vary by `type`.
      required:
        - type
        - sequence_number
      properties:
        type:
          type: string
          enum:
            - response.created
            - response.in_progress
            - response.output_item.added
            - response.output_item.done
            - response.content_part.added
            - response.content_part.done
            - response.output_text.delta
            - response.output_text.done
            - response.reasoning_summary_part.added
            - response.reasoning_summary_part.done
            - response.reasoning_summary_text.delta
            - response.reasoning_summary_text.done
            - response.function_call_arguments.delta
            - response.function_call_arguments.done
            - response.completed
            - response.incomplete
            - response.failed
            - error
        sequence_number:
          type: integer
          description: Event sequence number, increasing monotonically from 0.
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Error message describing what went wrong
            type:
              type: string
              description: Error type
            code:
              type: string
              description: Error code
          required:
            - message
      required:
        - error
    ResponsesInputItem:
      description: >-
        An element of the input array, discriminated by `type`. When `type` is
        omitted the item is treated as `message`.
      oneOf:
        - $ref: '#/components/schemas/ResponsesMessageItem'
        - $ref: '#/components/schemas/ResponsesReasoningItem'
        - $ref: '#/components/schemas/ResponsesFunctionCallItem'
        - $ref: '#/components/schemas/ResponsesFunctionCallOutputItem'
        - $ref: '#/components/schemas/ResponsesAdditionalToolsItem'
    ResponsesTool:
      description: A tool definition, discriminated by `type`.
      oneOf:
        - $ref: '#/components/schemas/ResponsesFunctionTool'
        - $ref: '#/components/schemas/ResponsesNamespaceTool'
      discriminator:
        propertyName: type
        mapping:
          function:
            $ref: '#/components/schemas/ResponsesFunctionTool'
          namespace:
            $ref: '#/components/schemas/ResponsesNamespaceTool'
    ResponsesToolChoice:
      type: string
      enum:
        - auto
      description: >-
        Controls tool-calling behavior. With `auto`, the model decides whether
        to call a tool.
    ResponsesOutputItem:
      description: An element of the output array, discriminated by `type`.
      oneOf:
        - $ref: '#/components/schemas/ResponsesOutputReasoningItem'
        - $ref: '#/components/schemas/ResponsesOutputMessageItem'
        - $ref: '#/components/schemas/ResponsesOutputFunctionCallItem'
      discriminator:
        propertyName: type
        mapping:
          reasoning:
            $ref: '#/components/schemas/ResponsesOutputReasoningItem'
          message:
            $ref: '#/components/schemas/ResponsesOutputMessageItem'
          function_call:
            $ref: '#/components/schemas/ResponsesOutputFunctionCallItem'
    ResponsesUsage:
      type: object
      description: Token usage for this response.
      properties:
        input_tokens:
          type: integer
          description: Number of input tokens, including cached tokens.
        input_tokens_details:
          type: object
          properties:
            cached_tokens:
              type: integer
              description: Number of tokens served from the context cache.
            cache_write_tokens:
              type: integer
              description: Number of tokens written to the context cache.
        output_tokens:
          type: integer
          description: Number of output tokens, including reasoning tokens.
        output_tokens_details:
          type: object
          properties:
            reasoning_tokens:
              type: integer
              description: Number of tokens spent on reasoning.
        total_tokens:
          type: integer
          description: Total number of tokens.
    ResponsesMessageItem:
      type: object
      title: Message
      description: A conversation message. `type` may be omitted.
      required:
        - role
        - content
      properties:
        type:
          type: string
          enum:
            - message
        role:
          type: string
          enum:
            - user
            - assistant
            - developer
          description: Message role. `developer` is handled as a system instruction.
        content:
          description: Message content, either a string or an array of content parts.
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ResponsesInputContentPart'
        status:
          type: string
          enum:
            - completed
    ResponsesReasoningItem:
      type: object
      title: Reasoning
      description: >-
        Replays reasoning content from a previous turn. `content` takes
        precedence over `summary`.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - reasoning
        id:
          type: string
        summary:
          type: array
          items:
            type: object
            required:
              - type
              - text
            properties:
              type:
                type: string
                enum:
                  - summary_text
              text:
                type: string
        content:
          type: array
          items:
            type: object
            required:
              - type
              - text
            properties:
              type:
                type: string
                enum:
                  - reasoning_text
              text:
                type: string
        status:
          type: string
          enum:
            - completed
    ResponsesFunctionCallItem:
      type: object
      title: Function call
      description: Replays a function call.
      required:
        - type
        - call_id
        - name
        - arguments
      properties:
        type:
          type: string
          enum:
            - function_call
        id:
          type: string
        call_id:
          type: string
          description: Call ID paired with the matching `function_call_output`.
        name:
          type: string
        namespace:
          type: string
          description: Namespace the tool belongs to, returned for namespace tool calls.
        arguments:
          type: string
          description: JSON string of the function arguments.
        status:
          type: string
          enum:
            - completed
    ResponsesFunctionCallOutputItem:
      type: object
      title: Function call output
      description: Result of executing a function call.
      required:
        - type
        - call_id
        - output
      properties:
        type:
          type: string
          enum:
            - function_call_output
        call_id:
          type: string
          description: Same call ID as the matching `function_call`.
        output:
          description: Content returned by the tool.
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ResponsesInputContentPart'
        status:
          type: string
          enum:
            - completed
    ResponsesAdditionalToolsItem:
      type: object
      title: Additional tools
      description: >-
        Adds callable tools partway through a conversation, effective from the
        position of this item.
      required:
        - type
        - role
        - tools
      properties:
        type:
          type: string
          enum:
            - additional_tools
        id:
          type: string
        role:
          type: string
          enum:
            - developer
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ResponsesTool'
    ResponsesFunctionTool:
      type: object
      title: Function tool
      description: A function tool whose arguments are described by a JSON Schema.
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - function
        name:
          type: string
          description: >-
            Function name. Must follow the regex:
            ^[a-zA-Z_][a-zA-Z0-9-_]{0,127}$
          pattern: ^[a-zA-Z_][a-zA-Z0-9-_]{0,127}$
        description:
          type: string
        parameters:
          type: object
          description: JSON Schema describing the function arguments.
        strict:
          type: boolean
    ResponsesNamespaceTool:
      type: object
      title: Namespace tool
      description: Groups a set of function tools under a single namespace.
      required:
        - type
        - name
        - description
        - tools
      properties:
        type:
          type: string
          enum:
            - namespace
        name:
          type: string
        description:
          type: string
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ResponsesFunctionTool'
    ResponsesOutputReasoningItem:
      type: object
      title: Reasoning
      description: Reasoning content produced by the model.
      properties:
        type:
          type: string
          enum:
            - reasoning
        id:
          type: string
          example: rs_68f0c1c2d3e4f5a6b7c8d9e0
        summary:
          type: array
          description: The reasoning content.
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - summary_text
              text:
                type: string
        encrypted_content:
          type:
            - string
            - 'null'
          description: Always `null`.
        status:
          type: string
          enum:
            - in_progress
            - completed
    ResponsesOutputMessageItem:
      type: object
      title: Message
      description: Text reply produced by the model.
      properties:
        type:
          type: string
          enum:
            - message
        id:
          type: string
          example: msg_68f0c1c2d3e4f5a6b7c8d9e0
        role:
          type: string
          enum:
            - assistant
        content:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - output_text
              text:
                type: string
              annotations:
                type: array
                items: {}
        status:
          type: string
          enum:
            - in_progress
            - completed
    ResponsesOutputFunctionCallItem:
      type: object
      title: Function call
      description: A function call initiated by the model.
      properties:
        type:
          type: string
          enum:
            - function_call
        id:
          type: string
          example: fc_68f0c1c2d3e4f5a6b7c8d9e0
        call_id:
          type: string
          description: Use this value in `function_call_output` when returning the result.
        name:
          type: string
        namespace:
          type: string
          description: Returned for namespace tool calls.
        arguments:
          type: string
          description: JSON string of the function arguments.
        status:
          type: string
          enum:
            - in_progress
            - completed
    ResponsesInputContentPart:
      description: An element of a content array, discriminated by `type`.
      oneOf:
        - type: object
          title: Input text
          required:
            - type
            - text
          properties:
            type:
              type: string
              enum:
                - input_text
            text:
              type: string
        - type: object
          title: Input image
          required:
            - type
            - image_url
          properties:
            type:
              type: string
              enum:
                - input_image
            image_url:
              type: string
              description: >-
                Data URL of the image, for example
                `data:image/png;base64,<base64>`. Public http(s) URLs are not
                supported.
            detail:
              type: string
              enum:
                - auto
                - low
                - high
                - original
        - type: object
          title: Output text
          description: Used when replaying assistant text from history.
          required:
            - type
            - text
          properties:
            type:
              type: string
              enum:
                - output_text
            text:
              type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        The Authorization header expects a Bearer token. Use an MOONSHOT_API_KEY
        as the token. This is a server-side secret key. Generate one on the [API
        keys page](https://platform.kimi.ai/console/api-keys) in your dashboard.

````