​

Using Chat Completions API via Responses API

This guide provides a comprehensive mapping to help you use the Chat Completions API functionality through the Responses API interface.

​

Property Mappings

​

Request Parameters

​

Implementation Details

The Open-Responses platform handles several complex mappings between Responses API and Chat Completions API that are worth noting:

​

Input Message Conversion (Handled by Open-Responses)

The conversion between input and messages involves complex logic:

• Role-Based Processing: Messages are handled differently based on role:

  • user: Converted to user message with appropriate content parts
  • assistant: Converted to assistant message
  • system: Converted to system message and concatenated with instructions
  • developer: Converted to developer message and concatenated with instructions
  • tool: Converted to tool message

• Content Handling: Different content types are processed specifically:

  • Text input: Directly mapped as text content
  • Image input: Converted to image URL parameters with detail settings
  • File input: Mapped to file references with appropriate metadata

​

Tool Integration (Handled by Open-Responses)

Tools conversion is more sophisticated than documented:

• Tool Types Support: The platform handles specific tool types:

  • Function tools: Complete definition with parameters converted
  • Web search tools: Mapped to function definitions with appropriate naming (Via Hosted Tool)
  • File search tools: Converted with configuration parameters (COMING SOON)
  • Computer use preview tools: Mapped to appropriate function calls (COMING SOON)

• Tool Choice Conversion: Tool choice is converted based on type:

  • Options-based choice: Mapped to auto or none
  • Function-based choice: Mapped to specific function name reference
  • Types-based choice: Mapped to type identifier

​

Response Format Handling (Handled by Open-Responses)

The conversion between text.format and response_format includes:

• Format Types:
  • Text format: Direct mapping to text response
  • JSON Object format: Mapped to structured JSON output
  • JSON Schema format: Complex mapping with schema definition conversion

​

System Interaction (Handled by Open-Responses)

• Instructions Merging: When system messages exist in the input, instructions are appended rather than replacing
• System Message Priority: System messages from the input take precedence over separate instruction fields

​

Reasoning Configuration (Handled by Open-Responses)

• Reasoning Effort: Converted to the appropriate ReasoningEffort enum value
• Reasoning Summary: Generated separately in the response based on model output

​

Hosted Tool Call Processing (Handled by Open-Responses)

• Hosted Function Calls: Processed in sequence and fed-back to the completion API for response generation.

​

Response Properties

​

Streaming Implementation (Handled by Open-Responses)

Streaming events in the Responses API are mapped to Chat Completions API events through a customized conversion process:

• Event Mapping: Each Responses API event corresponds to specific Chat Completions delta chunks:

  • Initial events (response.created) are generated when streaming starts
  • Content delta events map to content updates in Chat Completions
  • Tool call events are carefully synchronized with function call chunks

• State Management: The Open-Responses layer maintains internal state to ensure:

  • Proper sequencing of events
  • Tracking of incremental content updates
  • Appropriate event aggregation

• Chunk Processing: The platform handles:

  • Parsing of delta chunks from Chat Completions API
  • Transforming chunks to appropriate event types
  • Managing content buffering and flushing

​

Streaming Events Mapping

The table below shows the detailed mapping between Responses API streaming events and Chat Completions API events:

Note: For tool-specific events, {tool_name} is replaced with the actual name of the tool being executed, converted to lowercase with leading non-word characters replaced by underscores. These Open-responses managed tool events provide detailed visibility into the tool execution lifecycle beyond what the standard Chat Completions API offers.

​

Implementation Specifics

The Open-Responses implementation includes following components for streaming:

1. Event Buffer Management:

   • Maintains partial content state across stream chunks
   • Assembles coherent events from partial data
   • Manages tool call state across multiple chunks

2. Custom Event Generation:

   • Creates Open-Responses-specific events for enhanced user experience
   • Provides finer-grained progress indication than Chat Completions API
   • Handles special cases like content refusals

3. Error and Edge Case Handling:

   • Graceful processing of premature stream termination
   • Recovery from temporary connection issues
   • Special handling for content moderation interruptions

4. Tool Call Streaming:

   • Synchronization between tool calls and results
   • Progress indication for tool execution
   • Proper sequencing of multi-turn tool interactions

​

Open-responses Managed Tool Lifecycle Events

Open-Responses extends the standard Chat Completions API streaming events with Open-responses managed tool-specific events that provide more granular visibility into tool execution:

1. Tool Execution Progress Events:

   • response.{tool_name}.in_progress: Emitted when a tool call is detected and processing begins
   • response.{tool_name}.executing: Emitted when the tool is actively executing
   • response.{tool_name}.completed: Emitted when the tool execution completes successfully

2. Event Format: Each tool event includes standardized metadata:

   {
     "item_id": "tool-call-id",
     "output_index": "0",
     "type": "response.{tool_name}.{status}"
   }
   

3. Benefits:

   • Real-time visibility into hosted tool execution
   • Better UX with tool-specific progress indicators
   • Ability to show appropriate loading states for long-running tools
   • Troubleshooting visibility for tool execution issues

​

Open-responses Managed Tools

Open-responses managed tools are specialized tool implementations that are handled entirely by the Open-Responses platform rather than being passed directly to the underlying model provider or client. These tools provide additional functionality and enhanced capabilities not available in the standard Model provider API.

​

Key Characteristics of Open-responses Managed Tools

1. Execution Environment:

   • Tools run in a secure, isolated environment maintained by the Open-Responses platform
   • Execution happens server-side with appropriate security measures

2. Tool Types:

   • Web Search Tools: Allow models to search the internet and retrieve up-to-date information
   • File Search Tools: Enable searching and retrieving content from developer-provided files (COMING SOON)
   • Computer Use Tools: Provide limited, controlled access to computing resources for specific tasks (COMING SOON)
   • Custom Function Tools: Support for additional specialized tools maintained by the platform

3. Lifecycle Management:

   • Open-Responses manages the complete execution lifecycle of these tools
   • Tools are executed asynchronously and can be monitored through specialized events
   • Results are automatically fed back to the model during conversation

4. Benefits Over Standard Tool Calls:

   • Enhanced security through isolation and permission controls
   • Improved performance through optimized execution
   • Additional capabilities not natively supported by model providers
   • Simplified developer experience with unified API surface

​

Using Open-responses Managed Tools

To use these tools, developers specify them like regular tools but with special configuration parameters (currently MCPs) that indicate they should be managed by the Open-Responses platform.

The platform automatically handles:

• Tool execution and result processing
• Streaming events for tool execution progress
• Error handling
• Formatting and presenting results to the model

These tools enable powerful functionality like real-time web search, file operations, and other capabilities while maintaining a simple, consistent API surface for developers.

​

Open-Responses Layer Managed Properties

When using Chat Completions API via Responses API, the following Responses API features have limited or no direct support in the standard Chat Completions API and require special handling by the Open-Responses platform:

​

Conversation Management (Open-Responses-Managed)

• previous_response_id: Conversation history tracking and chaining
  • Open-Responses maintains conversation state between requests
  • Reconstructs message history based on previous interactions
  • Not directly supported in Chat Completions API

​

Response Control (Open-Responses-Managed) (COMING SOON)

• truncation Strategy:
  • auto: Open-Responses implements automatic content truncation based on token limits
  • disabled: Platform ensures complete responses without truncation
  • Custom handling required as Chat Completions has simpler max token controls

​

Output Customization (Open-Responses-Managed) (COMING SOON)

• include Parameter:
  • Controls which components appear in the response
  • Open-Responses filters response objects based on these specifications
  • Not directly available in Chat Completions API

​

Reasoning Features (Open-Responses-Enhanced)

• reasoning.generate_summary:
  • Open-Responses extracts and generates reasoning summaries from model outputs
  • Platform performs additional processing to extract reasoning patterns

​

Additional Open-Responses-Specific Enhancements

1. Error Handling:

   • Enhanced error reporting with detailed status codes
   • User-friendly error messages with recovery suggestions
   • Consistent error format across all response types

2. Metadata Management:

   • Preservation of metadata between requests and responses
   • Additional context tracking not available in Chat Completions
   • Custom fields for application-specific requirements

3. Request Normalization:

   • Automatic handling of various input formats
   • Standardization of inconsistent parameters
   • Backward compatibility with legacy request formats

4. Response Format Standardization:

   • Consistent output structure regardless of request variations
   • Normalized tool call formats across different model versions
   • Backward compatible output for different client versions

​

Modality Support (COMING SOON)

Both interfaces will support:

• Multimodal inputs (text, image, audio)
• Audio outputs

​

Implementation Notes

When using Chat Completions functionality through the Responses API, follow these best practices based on how the Open-Responses platform processes your requests:

​

Input Structure Best Practices

• Message Organization:

  • Structure your input as a well-formed array of messages with clear roles
  • Use appropriate role types (user, assistant, system, developer, tool)
  • Place system messages before user messages for consistent processing

• Content Formatting:

  • Provide multimodal content (text, images, files) as structured objects
  • Use consistent formatting for each content type
  • Follow content structure requirements exactly to avoid conversion errors

• Tool Definition:

  • Define tools completely with all required parameters
  • Use consistent naming across tool definitions and calls
  • Prefer function-type tools for best compatibility

​

Processing Considerations

• System Instructions:

  • When using both instructions and system messages in input, be aware they will be concatenated
  • System messages in input take precedence in positioning
  • Use only one approach (either instructions or system messages) for clarity

• Tool Call Handling:

  • Multi-turn tool calls are processed recursively by Open-Responses
  • Tool call IDs are crucial for proper mapping between calls and responses
  • Limit the number of tool calls to avoid hitting platform limits

• Response Processing:

  • Structure parsers to handle the normalized output format
  • For streaming, process events based on the event mapping table
  • Handle both success and error states appropriately

• Tool Event Processing:

  • Listen for tool-specific events (response.{tool_name}.*) to provide better UX during tool execution
  • Use the item_id and output_index in tool events to correlate with the associated function calls
  • Implement appropriate loading states based on each tool’s lifecycle events
  • For long-running tools, show progress indicators during the executing phase

​

Example API Calls

The following examples demonstrate how to structure requests for the Responses API, with comments explaining how Open-Responses processes each one:

​

Basic Text Completion

# This example shows a simple text input
# Open-Responses processes this by:
# 1. Converting the string input to a user message
# 2. Creating a User message
# 3. Setting the content directly as text
curl -X POST https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "model": "gpt-4o",
  "input": "Hello, world!"
}'

​

Completion with Instructions

# This example demonstrates using instructions
# Open-Responses processes this by:
# 1. Creating a system message with the instructions
# 2. Adding it before the user message
# 3. Setting appropriate roles for each message
curl -X POST https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "model": "gpt-4o",
  "instructions": "Answer concisely.",
  "input": "Explain AI."
}'

​

Completion with Temperature Adjustment

# This example shows parameter passing
# Open-Responses directly maps the temperature parameter to ChatCompletions
curl -X POST https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "model": "gpt-4o",
  "temperature": 0.5,
  "input": "Suggest a creative startup idea."
}'

​

Structured JSON Output

# This example demonstrates JSON formatting
# Open-Responses processes this by:
# 1. Converting text.format to response_format
# 2. Setting the appropriate JSON schema parameters
# 3. Configuring the model to return structured output
curl -X POST https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
    "model": "gpt-4o-2024-08-06",
    "input": [
      {
        "role": "system",
        "content": "You are a helpful math tutor. Guide the user through the solution step by step."
      },
      {
        "role": "user",
        "content": "how can I solve 8x + 7 = -23"
      }
    ],
    "text": {
      "format": {
        "type": "json_schema",
        "name": "math_reasoning",
        "schema": {
          "type": "object",
          "properties": {
            "steps": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "explanation": { "type": "string" },
                  "output": { "type": "string" }
                },
                "required": ["explanation", "output"],
                "additionalProperties": false
              }
            },
            "final_answer": { "type": "string" }
          },
          "required": ["steps", "final_answer"],
          "additionalProperties": false
        },
        "strict": true
      }
    }
  }'

​

Multimodal Text & Image Input

# This example shows multimodal input handling
# Open-Responses processes this by:
# 1. Converting each content item to content part objects
# 2. Creating appropriate type-specific handlers for text and image
# 3. Setting detail parameters for the image
curl -X POST https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
    "model": "gpt-4o",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "input_text", "text": "what is in this image?"},
          {
            "type": "input_image",
            "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
          }
        ]
      }
    ]
  }'

​

Using Tools

# This example demonstrates tool usage
# Open-Responses processes this by:
# 1. Converting tool definitions to completion tools objects
# 2. Setting up the appropriate function structure
# 3. Handling tool calls and responses through recursive processing
curl -X POST https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
    "model": "gpt-4o",
    "input": "What is the weather like in Boston today?",
    "tools": [
      {
        "type": "function",
        "name": "get_current_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["location", "unit"]
        }
      }
    ],
    "tool_choice": "auto"
  }'

​

Streaming Response

# This example shows streaming configuration
# Open-Responses handles this by:
# 1. Setting up an SSE connection
# 2. Converting Chat Completion chunks to Responses API events
# 3. Managing state across streamed chunks
curl -N -X POST https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "model": "gpt-4o",
  "input": "Stream your response.",
  "stream": true
}'

​

With Metadata

# This example demonstrates metadata handling
# Open-Responses preserves and passes through metadata (Coming soon)
# This is useful for request tracing and client-side state management 
curl -X POST https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "model": "gpt-4o",
  "input": "Metadata example.",
  "store": true,
  "metadata": {
    "request_id": "12345",
    "user": "test_user"
  }
}'

​

Handling Tool-Specific Events

// Example client code for handling tool-specific events during streaming
const response = await fetch('https://api.openai.com/v1/responses', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    model: "gpt-4o",
    input: "Execute the weather tool for Boston, then analyze the results.",
    tools: [{
      type: "function",
      name: "get_weather",
      // tool definition...
    }],
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

// Track tool execution state
const toolExecutionState = new Map();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n\n').filter(line => line.trim() !== '');
  
  for (const line of lines) {
    if (!line.startsWith('data:')) continue;
    
    const data = JSON.parse(line.substring(5));
    const eventType = data.type || '';
    
    // Handle standard events
    if (eventType === 'response.output_text.delta') {
      // Process text output...
    } 
    // Handle tool lifecycle events
    else if (eventType.startsWith('response.get_weather.')) {
      const toolId = data.item_id;
      const status = eventType.split('.').pop(); // in_progress, executing, completed
      
      if (status === 'in_progress') {
        toolExecutionState.set(toolId, { status: 'starting' });
        showToolLoadingUI(toolId, 'Starting weather lookup...');
      } 
      else if (status === 'executing') {
        toolExecutionState.set(toolId, { status: 'running' });
        showToolLoadingUI(toolId, 'Fetching weather data...');
      }
      else if (status === 'completed') {
        toolExecutionState.set(toolId, { status: 'completed' });
        updateToolLoadingUI(toolId, 'Weather data retrieved!');
      }
    }
  }
}

// UI helper functions
function showToolLoadingUI(toolId, message) {
  // Update UI with loading indicator for the specific tool
}

function updateToolLoadingUI(toolId, message) {
  // Update loading UI with status message
}

​

Request flow: