Skip to main content
The Responses API (POST /v1/responses) is OpenAI’s next-generation unified interface that handles text, images, file references, and tool sequences within a single request-response cycle. Through Fhddos, you get full streaming support, backward-compatible event handling, and extra billing metadata — without changing how you structure your requests. This page covers the request format, streaming events, tool calling, and practical tips for production use.

​
Endpoint

POST /v1/responses

​
Basic request

Send a multimodal message by passing input as a structured array of content parts. The role/content shape is familiar from Chat Completions, but the input field is more flexible — it accepts strings, arrays of typed objects, or a mix of both.
cURL
curl -X POST "$BASE_URL/v1/responses" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "Summarise the key points in the attached document."}
        ]
      }
    ],
    "response_format": {"type": "json_schema"}
  }'
Prefer the array form for input — it makes mixing text, images, and file references straightforward without restructuring your code later.

​
Streaming

Enable streaming by adding "stream": true to the request body. The server returns incremental updates as server-sent events (SSE). Fhddos includes built-in backward-compatibility processing, so you can consume the stream with standard SSE clients. Key event types you will encounter in a streamed response:
EventDescription
response.output_item.addedA new output item (text delta or tool call) has been added.
response.output_item.doneAn output item is complete.
response.completedThe full response is finished; carries a usage summary.
cURL (streaming)
curl -N -X POST "$BASE_URL/v1/responses" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "input": "What are the three laws of thermodynamics?",
    "stream": true
  }'
When you need to bridge a Responses stream to a client expecting the Chat Completions stream format, Fhddos’s built-in compatibility layer handles the translation automatically.

​
Tool calling

Declare available functions in the tools array, exactly as you would in Chat Completions. When the model decides to call a tool, the result appears in the output array under a tool_calls field. Return the tool result in a follow-up input entry with role: "tool".
cURL
curl -X POST "$BASE_URL/v1/responses" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "input": [
      {"role": "user", "content": "What flights are available from London to Tokyo tomorrow?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "search_flights",
          "description": "Search available flights between two cities on a given date.",
          "parameters": {
            "type": "object",
            "properties": {
              "origin": {"type": "string"},
              "destination": {"type": "string"},
              "date": {"type": "string", "description": "ISO 8601 date"}
            },
            "required": ["origin", "destination", "date"]
          }
        }
      }
    ]
  }'

​
Structured output

Pass "response_format": {"type": "json_schema"} to force the model to return a valid JSON object. Combine this with a detailed system prompt — or an inline schema — to get machine-readable output every time.
cURL
curl -X POST "$BASE_URL/v1/responses" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "input": "Extract the product name, price, and SKU from: Blue Widget, $29.99, SKU-4821",
    "response_format": {"type": "json_schema"}
  }'

​
Multi-turn conversations

Build conversation history by adding multiple role/content entries to the input array. There is no separate conversation state — include the full context you need in each request. 
{
  "model": "gpt-4.1",
  "input": [
    {"role": "user", "content": "My name is Alex."},
    {"role": "assistant", "content": "Nice to meet you, Alex!"},
    {"role": "user", "content": "What is my name?"}
  ]
}

​
Tips and gotchas

When you enable built-in tools such as Web Search Preview, Code Interpreter, or File Search, Fhddos appends additional billing metadata to the usage object. Review the console’s billing reconciliation page to account for these charges accurately.
  • Use the array form of input to mix text, images, and file references in one request.
  • The response_format field accepts json_schema and text; combine it with Fhddos’s rate-limit controls for reliable automated pipelines.
  • Tool call results appear in output[].tool_calls; pass them back inside a role: "tool" input entry on the next turn.

​
Request parameters

​
model
string
required
Model ID, e.g. gpt-4.1. Use GET /v1/models to list models your token can access.
​
input
string | array
required
The input to the model. Pass a plain string for simple text prompts, or an array of {role, content} objects for multimodal or multi-turn input. content may itself be an array of typed parts (text, image_url, etc.).
​
response_format
object
{"type": "json_schema"} forces structured JSON output. {"type": "text"} returns plain text.
​
tools
array
Function definitions the model may call. Each entry follows the same schema as Chat Completions tools.
​
stream
boolean
Set to true to receive incremental output via SSE. Defaults to false.