# /v1/responses API Documentation

> **Important Note**: Our service is fully compatible with the OpenAI Responses API standard, and we strongly recommend referring directly to the [OpenAI official API documentation](https://platform.openai.com/docs/api-reference/responses/create) for the most comprehensive and up-to-date parameter details and examples. This allows you to leverage OpenAI's rich resources (such as tutorials and SDKs). The following is a streamlined interface overview focusing on core fields and usage instructions to reduce complexity from too many parameters (complete parameter set is about 30, only necessary/common ones are listed). For advanced features or a complete list, please refer to the official documentation.

## Overview

`/v1/responses` is OpenAI's most advanced response generation interface, supporting text/image inputs, text/JSON outputs, multi-turn dialogue, tool invocation (such as web search, file search), and background processing. It is suitable for stateful interactions and external data integration. Request method: POST. Endpoint: https://api-us-ca.umodelverse.ai/v1/responses (compatible with OpenAI format).

**Authentication**: Use API key, passed via `Authorization: Bearer {api_key}`.
**Note**: With about 30 parameters, it is recommended to start with core ones. Supports streaming responses and tool extensions. Some parameters (like reasoning) are only applicable to o-series models.

## Main Core Fields

### Request Parameters

Selected essential and common fields (about 10), for full list refer to the official documentation.

| Field               | Type          | Required | Default | Description |
|---------------------|---------------|----------|---------|-------------|
| input               | string        | No       | None    | Input content (text/image/file). |
| model               | string        | Yes      | None    | Model ID, such as `gpt-4o` or `o3`. Meaning: Specify response generation model. |
| instructions        | string        | No       | None    | System message. Meaning: Guide model behavior, can override previous instructions. |
| max_tokens          | integer       | No       | None    | Maximum output tokens (including reasoning). Meaning: Control response length. |
| tools               | array         | No       | None    | Tool list (e.g., function/web search). Meaning: Expand model capabilities. |
| tool_choice         | string/object | No       | auto    | Tool choice (e.g., `auto`). Meaning: Decide whether to invoke a tool. |
| stream              | boolean       | No       | false   | Whether to stream. Meaning: Return event stream in real-time. |
| temperature         | number        | No       | 1       | Sampling temperature (0-2). Meaning: Control randomness. |
| top_p               | number        | No       | 1       | Nucleus sampling (0-1). Meaning: Control diversity, mutually exclusive with temperature. |
| background          | boolean       | No       | false   | Whether to run in the background. Meaning: Asynchronous processing, suitable for long tasks. |

* **Simplification Tip**: Other common ones such as `previous_response_id` (multi-turn dialogue), `reasoning` (reasoning configuration). Avoid non-essential parameters to simplify invocation.

### Response

Core response object, returns event sequences when streaming.

| Field             | Type    | Description |
|-------------------|---------|-------------|
| output            | array   | Generated content (such as text/tool invocation). Meaning: Model's output result. |
| status            | string  | Status (e.g., `completed`, `failed`). Meaning: Response processing result. |
| created           | number  | Creation timestamp. Meaning: Unix seconds. |
| id                | string  | Response ID. Meaning: Unique identifier. |
| model             | string  | Model used. Meaning: Confirm model. |
| usage             | object  | Token usage statistics. Meaning: Basis for billing. |

* **Streaming Events**: Such as `response.created`, `response.output_item.added`, etc. Ends with `response.done`. Full event list available in the official documentation.

## Usage Documentation

### Basic Process
1. **Construct Request**: Specify model and input_items.
2. **Send Request**: POST with key.
3. **Parse Response**: Extract output content.
4. **Streaming**: Handle event stream.

### Example (Curl, Non-Streaming)
```
curl https://api-us-ca.umodelverse.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "model": "{model_name}",
    "input": "Hello! Who are you?"
  }'
```

Expected Response (Simplified):
```json
{
  "id": "resp-123",
  "object": "response",
  "created": 1677652288,
  "model": "gpt-4o",
  "output": [{"type": "text", "text": "Hi!"}],
  "status": "completed",
  "usage": {"total_tokens": 20}
}
```

### Example (Python, Streaming)
```python
import openai

client = openai.OpenAI(api_key="{api_key}", base_url="https://api-us-ca.umodelverse.ai/v1/")
stream = client.responses.create(
    model="{model_name}",
    input_items=[{"type": "text", "text": "Hello!"}],
    stream=True
)
for event in stream:
    print(event)  # Like response.delta
```

For more details, please refer directly to the [OpenAI official documentation](https://platform.openai.com/docs/api-reference/responses/create).