{"record":{"id":"e55dc8b6994b0bb7","repo":"openai/openai-python","slug":"you-tried-to-pass-a-basemodel-class-to-chat-com","errorCode":null,"errorMessage":"You tried to pass a `BaseModel` class to `chat.completions.create()`; You must use `chat.completions.parse()` instead","messagePattern":"You tried to pass a `BaseModel` class to `chat\\.completions\\.create\\(\\)`; You must use `chat\\.completions\\.parse\\(\\)` instead","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/openai/resources/chat/completions/completions.py","lineNumber":3409,"sourceCode":"        )\n        self.list = async_to_streamed_response_wrapper(\n            completions.list,\n        )\n        self.delete = async_to_streamed_response_wrapper(\n            completions.delete,\n        )\n\n    @cached_property\n    def messages(self) -> AsyncMessagesWithStreamingResponse:\n        \"\"\"\n        Given a list of messages comprising a conversation, the model will return a response.\n        \"\"\"\n        return AsyncMessagesWithStreamingResponse(self._completions.messages)\n\n\ndef validate_response_format(response_format: object) -> None:\n    if inspect.isclass(response_format) and issubclass(response_format, pydantic.BaseModel):\n        raise TypeError(\n            \"You tried to pass a `BaseModel` class to `chat.completions.create()`; You must use `chat.completions.parse()` instead\"\n        )\n","sourceCodeStart":3391,"sourceCodeEnd":3412,"githubUrl":"https://github.com/openai/openai-python/blob/9917c6e28e66e90e1227b3d223c06a8c5441515a/src/openai/resources/chat/completions/completions.py#L3391-L3412","documentation":"validate_response_format rejects passing a pydantic BaseModel subclass as response_format to chat.completions.create(). Structured outputs via a BaseModel class require the dedicated client.beta.chat.completions.parse() method, which handles schema generation and parsing; create() only accepts a dict-based response_format (e.g. json_schema specs). This is a TypeError raised synchronously before any request.","triggerScenarios":"`client.chat.completions.create(model=\"gpt-4o\", messages=[...], response_format=MyPydanticModel)` where MyPydanticModel subclasses pydantic.BaseModel.","commonSituations":"Migrating code from the parse() structured-output API back to create(), or following tutorials that show structured outputs and wiring the model class into the wrong method; also passing a BaseModel where a `{\"type\": \"json_schema\", ...}` dict is expected.","solutions":["Use `client.beta.chat.completions.parse(..., response_format=MyModel)` for typed structured outputs.","If you must use create(), pass a dict spec such as `{\"type\": \"json_schema\", \"json_schema\": {\"name\": \"my_schema\", \"schema\": MyModel.model_json_schema()}}` (per the chat.completions.create docs).","Do not pass the class anywhere else (e.g. inside message content)."],"exampleFix":"# before\ncompletion = client.chat.completions.create(\n    model=\"gpt-4o\", messages=[...], response_format=MyModel\n)\n# after\ncompletion = client.beta.chat.completions.parse(\n    model=\"gpt-4o\", messages=[...], response_format=MyModel\n)\n# or with create():\ncompletion = client.chat.completions.create(\n    model=\"gpt-4o\", messages=[...],\n    response_format={\"type\": \"json_schema\", \"json_schema\": {\"name\": \"out\", \"schema\": MyModel.model_json_schema(), \"strict\": True}},\n)","handlingStrategy":"type-guard","validationCode":"import pydantic\n\ndef check_response_format(rf: object) -> None:\n    if inspect.isclass(rf) and issubclass(rf, pydantic.BaseModel):\n        raise TypeError(\"use client.beta.chat.completions.parse() for BaseModel response_format\")","typeGuard":"def uses_base_model(rf: object) -> bool:\n    import inspect, pydantic\n    return inspect.isclass(rf) and issubclass(rf, pydantic.BaseModel)\n\n# route: parse() if uses_base_model(fmt) else create()","tryCatchPattern":"try:\n    completion = client.chat.completions.create(..., response_format=fmt)\nexcept TypeError as e:\n    if \"parse()\" in str(e):\n        completion = client.beta.chat.completions.parse(..., response_format=fmt)\n    else:\n        raise","preventionTips":["Use parse() whenever response_format is a pydantic model.","For create(), pass a {\"type\": \"json_schema\", ...} dict built from Model.model_json_schema()."],"tags":["python","openai","pydantic","structured-output","typeerror","chat-completions"],"backgroundTag":"wrong-api-method-for-structured-output","analyzedSha":"9917c6e28e66e90e1227b3d223c06a8c5441515a","analyzedAt":"2026-08-28T11:46:34.183Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}