​

Using Chat Completions API via Responses API

​

Property Mappings

​

Request Parameters

​

Implementation Details

​

Input Message Conversion (Handled by Open-Responses)

• 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)

• 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)

• 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)

• 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

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

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

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:
   Copy

   {
     "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

​

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

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

​

Open-Responses Layer Managed Properties

​

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)

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

​

Implementation Notes

​

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

​

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": "openai@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": "openai@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": "openai@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": "openai@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": "openai@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": "openai@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": "openai@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": "openai@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: "openai@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: