Responses API vs Chat Completions

Responses API and Chat Completions both send prompts to language models, but they organize input, output, tools, and streaming differently. Choosing between them should start with the client and model contract—not with the assumption that a newer endpoint automatically works for every provider.

The shortest decision rule is:

• Use Responses API for a coding agent or application that already expects Responses items, tool events, and the Responses streaming lifecycle.
• Use Chat Completions for broadly compatible chat clients and for provider families that expose their OpenAI-style models through raw Chat Completions pass-through.

Always verify the selected model's supported API format in Models & Pricing.

Protocol comparison

The table describes the wire contract. It does not imply that Modelflare converts every provider feature between the two formats.

When Responses API is the better fit

Choose /v1/responses when the client already treats a model run as a sequence of typed items rather than one assistant message. This is common in coding agents that need to distinguish visible text, reasoning summaries, function arguments, custom tool input, and other events.

A minimal request looks like:

curl -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "List the three checks to make before an API migration.",
    "stream": true
  }'

Responses streaming should be validated end to end. A client that understands Chat Completions chunks but not Responses events can connect successfully and still fail to render useful output.

When Chat Completions is the safer choice

Choose /v1/chat/completions when the application is built around system, user, assistant, and tool messages, or when the selected provider family documents an OpenAI-compatible Chat Completions endpoint.

curl -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [
      {"role": "system", "content": "Answer concisely."},
      {"role": "user", "content": "What should an API health check verify?"}
    ],
    "stream": true
  }'

For non-OpenAI provider families, Modelflare can expose raw Chat Completions pass-through so private request fields such as provider-specific reasoning or search controls reach the upstream service unchanged. That behavior is intentionally narrower than claiming full Responses compatibility.

Do not choose by model name alone

Three separate checks are required:

1. The API key can access the model. Access depends on the key and available model groups.
2. The model supports the endpoint. A model in /v1/models is not automatically valid for both request formats.
3. The client understands the stream. Responses events and Chat Completions chunks are different client contracts.

If any of these checks fail, switching the endpoint path alone may turn a clear compatibility error into an empty or partially rendered response.

Tool and structured-output migration

Before moving an existing integration:

• compare the tool definition schema used by the client;
• verify how tool-call IDs and tool outputs are returned;
• preserve explicit optional values instead of dropping 0 or false;
• check whether the provider requires private fields that must pass through unchanged;
• test tool-only responses that may not contain a visible text delta;
• confirm how the client detects completion and usage.

The same prompt producing similar text is not a sufficient protocol test. A real test should include the features the application depends on.

A practical selection flow

1. Open Models & Pricing and choose the model and group.
2. Confirm the supported API format.
3. Follow a client-specific guide in Modelflare Docs when one exists.
4. Send one non-streaming request.
5. Send one streaming request.
6. Exercise tools or structured output.
7. Review the request in usage logs for status, timing, token usage, and cost.

Responses API is not a universal replacement for Chat Completions, and Chat Completions is not obsolete. The correct format is the one jointly supported by the client, the selected model, and the upstream provider contract.