README "Nested params" example calls non-existent client.chat.responses.create and mixes two API surfaces

[kiwigitops]

Problem

The "Nested params" example in README.md (currently at lines 469–487 on main) is not runnable as written. It calls client.chat.responses.create(...), but the Chat resource only exposes completions — there is no responses attribute on client.chat. Running the snippet raises AttributeError: 'Chat' object has no attribute 'responses'.

The snippet as it appears today:

from openai import OpenAI

client = OpenAI()

response = client.chat.responses.create(
    input=[
        {
            "role": "user",
            "content": "How much ?",
        }
    ],
    model="gpt-5.2",
    response_format={"type": "json_object"},
)

There are two distinct problems mixed together:

1. client.chat.responses does not exist. src/openai/resources/chat/chat.py defines Chat with only a completions cached_property. The two valid namespaces are client.chat.completions (Chat Completions API) and client.responses (Responses API), not a hybrid.
2. The parameter shape doesn't match either API. input=[...] is the Responses API surface, while response_format={"type": "json_object"} is the Chat Completions parameter. The Responses API uses text={"format": {...}} for structured output, so even after fixing the namespace the snippet wouldn't work as a Responses example.

Since this section is meant to demonstrate "nested parameters are dictionaries, typed using TypedDict," it would be useful for it to be a real, runnable call so users copy-pasting it (and people relying on IDE/mypy type discovery from it) get a working example.

Suggested fix

Two reasonable options — pick whichever fits the README's intent better.

Option A — Chat Completions (matches the current response_format shape):

-response = client.chat.responses.create(
-    input=[
-        {
-            "role": "user",
-            "content": "How much ?",
-        }
-    ],
-    model="gpt-5.2",
-    response_format={"type": "json_object"},
-)
+response = client.chat.completions.create(
+    messages=[
+        {
+            "role": "user",
+            "content": "Can you generate an example json object describing a fruit?",
+        }
+    ],
+    model="gpt-5.2",
+    response_format={"type": "json_object"},
+)

Option B — Responses API (matches the current input=[...] shape):

response = client.responses.create(
    model="gpt-5.2",
    input="Generate an example JSON object describing a fruit.",
    text={"format": {"type": "json_object"}},
)

Happy to follow up with a small PR for whichever option a maintainer prefers.

Environment

• openai-python README on main as of 2026-05-18
• Reproducible against the current published SDK on PyPI (the missing client.chat.responses attribute is structural, not version-dependent)