---
title: "Generate a response"
method: POST
path: "/v1/responses"
tags: ["Responses"]
---

# Generate a response

`POST /v1/responses`

Create a response using the specified model and instructions.

## Request body

- object
  - `model` string, nullable
  - `input` union
    - string
    - union[]
      - union
        - object
          - `type` 'item_reference', required
          - `id` string, required
        - object
          - `type` 'message'
          - `role` 'user'
          - `id` string, nullable
          - `content` union, required
            - string
            - union[]
              - …
          - `status` string, nullable
        - object
          - `type` 'message'
          - `role` 'assistant'
          - `id` string, nullable
          - `content` union, required
            - string
            - union[]
              - …
          - `status` 'in_progress' | 'completed' | 'failed' | 'null', nullable
        - object
          - `type` 'message'
          - `role` 'system'
          - `id` string, nullable
          - `content` union, required
            - string
            - unknown[]
              - …
        - object
          - `type` 'message'
          - `role` 'developer'
          - `id` string, nullable
          - `content` union, required
            - string
            - unknown[]
              - …
        - object
          - `type` 'reasoning', required
          - `id` string, nullable
          - `summary` unknown[], required
            - unknown
          - `content` unknown[]
            - unknown
          - `encrypted_content` string
        - object
          - `type` 'compaction', required
          - `id` string, nullable
          - `encrypted_content` string, required
        - object
          - `type` 'mcp_approval_request', required
          - `id` string, nullable
          - `server_label` string, required
          - `name` string, required
          - `arguments` string, required
        - object
          - `type` 'mcp_approval_response', required
          - `id` string, nullable
          - `approval_request_id` string, required
          - `approve` boolean, required
          - `reason` string
        - object
          - `type` 'function_call', required
          - `id` string, nullable
          - `call_id` string, required
          - `name` string, required
          - `arguments` string, required
          - `status` 'in_progress' | 'completed' | 'failed'
        - object
          - `type` 'function_call_output', required
          - `id` string, nullable
          - `call_id` string, required
          - `output` union
            - string
            - unknown[]
              - …
        - object
          - `type` string, required
  - `previous_response_id` string, nullable
  - `include` string[]
  - `tools` union[], nullable
    - union
      - object
        - `type` 'function', required
        - `name` string, required
        - `description` string
        - `parameters` object, required
        - `strict` boolean
      - object
        - `type` 'computer-preview', required
        - `display_width` integer, required
        - `display_height` integer, required
        - `environment` unknown
      - object
        - `type` 'apply_patch', required
      - object
        - `type` 'mcp', required
        - `server_label` string, required
        - `server_url` string
        - `server_description` string
        - `authorization` string
        - `authorization_token` string
        - `headers` object
        - `allowed_tools` union
          - string[]
          - unknown
        - `require_approval` unknown
      - object
        - `type` 'image_generation', required
        - `model` unknown
        - `quality` 'low' | 'medium' | 'high' | 'auto'
        - `size` '1024x1024' | '1024x1536' | '1536x1024' | 'auto'
        - `output_format` 'png' | 'webp' | 'jpeg'
        - `output_compression` integer
        - `moderation` 'auto' | 'low'
        - `background` 'transparent' | 'opaque' | 'auto'
        - `input_fidelity` 'high' | 'low' | 'null', nullable
        - `input_image_mask` object
          - `image_url` string
          - `file_id` string
        - `partial_images` integer
        - `action` 'auto' | 'generate' | 'edit'
      - object
        - `type` 'web_search', required
      - object
        - `type` 'file_search', required
      - object
        - `type` 'code_interpreter', required
        - `env_vars` object
        - `timeout_ms` number
        - `sandbox_id` string
      - object
        - `type` string, required
  - `tool_choice` unknown
  - `mcp_servers` object[]
    - `type` 'url'
    - `url` string, uri, required
    - `name` string, required
    - `authorization_token` string
    - `allowed_tools` string[]
  - `metadata` object, nullable
  - `text` object, nullable
    - `format` object
      - `type` 'text' | 'json_object' | 'json_schema', required
  - `temperature` number, nullable
  - `top_p` number, nullable
  - `presence_penalty` number, nullable
  - `frequency_penalty` number, nullable
  - `parallel_tool_calls` boolean, nullable
  - `stream` boolean
  - `stream_options` unknown
  - `background` boolean
  - `max_output_tokens` integer, nullable
  - `max_tool_calls` integer, nullable
  - `reasoning` object, nullable
    - `effort` 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'null', nullable
    - `summary` 'auto' | 'concise' | 'detailed' | 'null', nullable
    - `encrypted_content` boolean, nullable
  - `user` string, nullable
  - `safety_identifier` string, nullable
  - `prompt_cache_key` string, nullable
  - `prompt_cache_retention` unknown
  - `truncation` 'auto' | 'disabled'
  - `instructions` string, nullable
  - `store` boolean
  - `service_tier` unknown
  - `top_logprobs` integer, nullable
  - `conversation` unknown

## Response `200`

Successful response

- object
  - `id` string, required
  - `object` 'response', required
  - `created_at` number, required
  - `status` 'queued' | 'in_progress' | 'completed' | 'failed', required
  - `model` string, required
  - `output` union[], required
    - union
      - object
        - `type` 'redacted_thinking', required
        - `id` string, required
        - `data` string, required
      - object
        - `type` 'reasoning', required
        - `id` string, required
        - `summary` object[]
          - `type` 'summary_text', required
          - `text` string, required
        - `content` unknown[]
          - unknown
        - `encrypted_content` string
      - object
        - `type` 'message', required
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `role` string, required
        - `content` union[], required
          - union
            - object
              - …
            - object
              - …
            - unknown
      - object
        - `type` 'function_call', required
        - `id` string, required
        - `call_id` string, required
        - `name` string, required
        - `arguments` string, required
        - `status` 'in_progress' | 'completed' | 'incomplete'
      - object
        - `type` 'function_call_output', required
        - `id` string, required
        - `call_id` string, required
        - `output` union
          - string
          - unknown[]
            - unknown
        - `status` 'in_progress' | 'completed' | 'incomplete'
      - object
        - `type` 'compaction', required
        - `id` string, nullable
        - `encrypted_content` string, required
        - `created_by` string
      - object
        - `type` 'mcp_list_tools', required
        - `id` string, required
        - `server_label` string, required
        - `tools` object[], required
          - `name` string, required
          - `description` string
          - `input_schema` object, required
      - object
        - `type` 'mcp_approval_request', required
        - `id` string, required
        - `server_label` string, required
        - `name` string, required
        - `arguments` string, required
      - object
        - `type` 'mcp_approval_response', required
        - `id` string, required
        - `approval_request_id` string, required
        - `approve` boolean, required
        - `reason` string
      - object
        - `type` 'code_interpreter', required
        - `id` string, required
        - `code_interpreter` object, required
          - `input` string, required
          - `sandbox_id` string
          - `outputs` union[], required
            - union
              - …
      - object
        - `type` 'image_generation_call', required
        - `id` string, required
        - `status` string
        - `result` string, nullable
        - `revised_prompt` string, nullable
  - `usage` unknown

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `429` — Rate Limit Exceeded

---

[API](https://skmtc.net/neosantara/apis/neosantara-ai-api.md) · [All operations](https://skmtc.net/neosantara/apis/neosantara-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/neosantara/neosantara-ai-api/revisions/82bc74ee8650/schema)