responses.create() vs chat.completions.create()

~22 min · responses-api, shape-diff

Level 0Tokenizer

0 XP0/54 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

While both APIs generate text, they differ in structure, defaults, and capabilities:

Structural Differences

Aspect	Chat Completions	Responses API
Input field	`messages` (array)	`input` (string or array)
System prompt	`{"role": "system"}`	`instructions` parameter
Output access	`choices[0].message.content`	`output_text` (convenience)
Storage default	`false`	`true`
Multi-turn	Manual message array	`previous_response_id`

Three concrete differences you'll notice immediately

(1) response.output_text exists on Responses and is the assistant's final string — no more completion.choices[0].message.content. (2) previous_response_id replaces resending the message array. (3) instructions= at the top level replaces the system-role message. Each is small; together they're a noticeably tighter shape.

The migration cost is dominated by tool-shape differences — see Custom Function Tools below for the top-level name/parameters vs nested function trap.

Code

Same task, both APIs·python

# Chat Completions
completion = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "developer", "content": "Be concise."},
        {"role": "user", "content": "What is 2+2?"},
    ],
)
print(completion.choices[0].message.content)

# Responses API — simpler
response = client.responses.create(
    model="gpt-5.4",
    instructions="Be concise.",
    input="What is 2+2?",
)
print(response.output_text)  # convenience property

External links

Response object (Responses)

Exercise

Make the same call (model + prompt) on both APIs. Print the JSON of each response side-by-side. Identify 5 fields that exist in one and not the other.