OpenAI Responses API

This platform provides a unified endpoint compatible with the OpenAI Responses API.

This document is intended for client-side integrators and focuses on the public request path, authentication method, request parameters, and example payloads. Aside from the differences in request and response protocol compared with Chat Completions, the supported model range is the same as /docs/api-reference/text/openai-chat-api.

Overview:

• Endpoint: POST /v1/responses
• Capability type: unified text generation / multi-turn input orchestration
• Response modes:
  • When stream = false or omitted: standard JSON response
  • When stream = true: text/event-stream SSE response
• Protocol style: the request body uses input as the primary field instead of the Chat Completions messages top-level structure

Current scope:

• Covers only POST /v1/responses
• Compared with /docs/api-reference/text/openai-chat-api, the main difference is protocol structure, not model availability
• Does not cover other OpenAI endpoints such as embeddings, images, or audio

1. API Overview

• HTTP method: POST
• Request path: /v1/responses
• Content-Type: application/json
• Response type:
  • Non-streaming: application/json
  • Streaming: text/event-stream

2. Authentication and Headers

Example headers:

Authorization: Bearer YOUR_REACH_API_KEY
Content-Type: application/json

At least one of Authorization or x-api-key must be provided.

Header details:

3. Request Body

The request body follows the common OpenAI Responses API object structure:

{
  "model": "YOUR_MODEL_ID",
  "input": "Please introduce yourself in one sentence.",
  "instructions": "You are a professional technical assistant.",
  "temperature": 0.2,
  "stream": false
}

3.1 Top-Level Parameters

3.2 input Parameter

input can be passed either as a plain string or as a structured array. Common forms include:

Text example:

"Please summarize the main idea of this document in one sentence."

Structured input example:

[
  {
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Please describe the image."
      },
      {
        "type": "input_image",
        "image_url": "https://cdn.example.com/demo.png"
      }
    ]
  }
]

4. Request Examples

4.1 Standard Non-Streaming Request

curl -X POST "https://direct.reachapi.ai/v1/responses" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "input": "Introduce ReachAPI in one sentence.",
    "temperature": 0.2
  }'

4.2 Streaming Request

curl -X POST "https://direct.reachapi.ai/v1/responses" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "input": "Summarize today'\''s priorities in three lines.",
    "stream": true
  }'

4.3 Request with Tool Definitions

curl -X POST "https://direct.reachapi.ai/v1/responses" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "input": "Help me check the weather in Shanghai.",
    "tools": [
      {
        "type": "function",
        "name": "get_weather",
        "description": "Get weather information for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            }
          },
          "required": ["city"]
        }
      }
    ],
    "tool_choice": "auto"
  }'

5. Successful Response

Example non-streaming response:

{
  "id": "resp_123",
  "object": "response",
  "created_at": 1710000000,
  "model": "YOUR_MODEL_ID",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "ReachAPI is a unified AI API platform for enterprise use."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 25,
    "output_tokens": 20,
    "total_tokens": 45
  }
}

Streaming response (SSE) example:

event: response.created
data: {"id":"resp_123","object":"response","status":"in_progress"}

event: response.output_text.delta
data: {"delta":"ReachAPI is a unified"}

event: response.output_text.delta
data: {"delta":" AI API platform for enterprise use."}

event: response.completed
data: {"id":"resp_123","status":"completed"}

6. Error Response

OpenAI-style error example:

{
  "error": {
    "message": "Field `input` is required",
    "type": "invalid_request_error",
    "param": null,
    "code": "MISSING_REQUIRED_FIELD"
  }
}

Common scenarios:

• Missing model in the request body
• Missing input in the request body
• Invalid JSON payload
• Authentication failure

7. Compatibility Notes

• This document lists commonly used fields and example payloads. Actual field names and structures follow the OpenAI Responses API.
• Compared with Chat Completions, the main differences in the Responses API are the input protocol (input / instructions) and the response structure.
• If you use newer or experimental official fields, validate them against the actual capabilities available on your gateway.

8. Main Differences from Chat Completions

9. Supported Models and Reference Pricing

The following prices are summarized from the unified pricing document. Aside from protocol differences, this endpoint supports the same model range as /docs/api-reference/text/openai-chat-api. Pricing was checked on 2026-04-17. For detailed pricing rules, refer to gpt.md.

Notes:

• Cached input refers to the unit price for cache-hit input tokens
• If the model list changes over time, use the dashboard or product configuration as the source of truth for currently enabled models

10. References

• OpenAI Responses API: https://platform.openai.com/docs/api-reference/responses/create
• OpenAI text generation guide: https://platform.openai.com/docs/guides/text
• OpenAI API errors: https://platform.openai.com/docs/guides/error-codes/api-errors
• Unified platform pricing document: gpt.md