---
title: "Responses API"
method: POST
path: "/v1/responses"
tags: ["Text Series"]
---

# Responses API

`POST /v1/responses`

Create a response from text, multimodal input, and optional tools.

## Request body

- ResponsesRequest
  - `model` string, required — Model name.
  - `input` union, required — Plain text input or an array of structured input items.
    - string
    - ResponsesInputItem[]
      - `role` 'system' | 'developer' | 'user' | 'assistant' — Input role.
      - `content` union — Input content.
        - string
        - ResponsesContentBlock[]
          - `type` string — Content block type, such as `input_text`, `input_image`, or `input_audio`.
          - `text` string — Text content for text blocks.
          - `image_url` string — Image URL or Base64 Data URI.
          - `audio` object — Audio payload, when supported by the selected model.
  - `instructions` string — System or developer instructions that guide the model response.
  - `tools` ResponsesTool[] — Tools available to the model. Tool support depends on the selected model.
    - `type` string, required — Tool type.
  - `tool_choice` union — Controls how the model selects tools.
    - string
    - object
  - `max_output_tokens` integer — Maximum number of output tokens to generate.
  - `max_tokens` integer — Legacy compatibility field for maximum output tokens.
  - `stream` boolean — Whether to use streaming output in SSE format.
  - `store` boolean — Whether the response should be stored when supported.
  - `reasoning` object — Reasoning configuration, when supported by the selected model.
  - `text` object — Text output configuration, such as structured output format options when supported.
  - `metadata` object — Custom metadata key-value pairs for your request.
  - `previous_response_id` string — Previous response ID for continuing a conversation.
  - `include` string[] — Additional response fields to include, when supported.
  - `parallel_tool_calls` boolean — Whether the model may call multiple tools in parallel.
  - `truncation` string — Truncation behavior for long context, when supported.
  - `user` string — End-user identifier for abuse monitoring and request tracing.
  - `background` boolean — Whether to run the response in background mode, when supported.
  - `service_tier` string — Service tier selection, when supported.
  - `prompt` object — Prompt object, when supported by the selected model.
  - `temperature` number — Controls output randomness, range 0-2.
  - `top_p` number — Nucleus sampling parameter, range 0-1.

## Response `200`

Response created

- ResponsesEnvelope
  - `code` integer
  - `data` ResponseObject — Response object.
    - `id` string
    - `object` string
    - `created_at` integer
    - `status` string
    - `model` string
    - `output` ResponseOutputItem[]
      - `id` string
      - `type` string
      - `status` string
      - `role` string
      - `content` ResponseContent[]
        - `type` string
        - `text` string
        - `annotations` object[]
    - `usage` ResponseUsage — Token usage statistics.
      - `input_tokens` integer
      - `output_tokens` integer
      - `total_tokens` integer
      - `input_tokens_details` object
      - `output_tokens_details` object

## Other responses

- `400` — Invalid request
- `401` — Invalid or missing API key
- `402` — Insufficient balance
- `429` — Rate limit exceeded
- `500` — Internal server error

---

[API](https://skmtc.net/poyo/apis/poyo-ai-hunyuan-3d-v3-1-api.md) · [All operations](https://skmtc.net/poyo/apis/poyo-ai-hunyuan-3d-v3-1-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/poyo/poyo-ai-hunyuan-3d-v3-1-api/revisions/4b46904b78eb/schema)