Output format is an API request setting that tells a model what shape its response should take. It turns a model from a free-form text generator into a pipeline component that can return data intended for programmatic use. This matters when results feed dashboards, databases, machine-learning steps, or DataFrames, where verbose explanations and inconsistent fields create parsing work and operational risk. section 5.3.2 section 6.2.2
Choose the format based on how much structure downstream code needs:
- Default text mode returns free-form content. It is flexible, but callers must parse it themselves and handle the resulting fragility. section 6.2.2
- JSON mode requests a JSON object with {"type": "json_object"}. It is useful for lightweight interchange, but malformed output remains possible with ambiguous prompts, so error handling is still needed. section 6.2.2
- A schema-enforced response uses a Pydantic BaseModel as the expected structure. Fields such as duplicates and drop_columns become a contract that can be parsed directly into a Python object. section 6.2.2 section 6.2.3
Return cleanup instructions as typed data
For a DataFrame containing duplicate records and an all-null optional_note column, define a CleanedData model with duplicates: List[int] and drop_columns: List[str]. Send records produced by df.to_dict(orient="records") with instructions split between a system message and a user message. With the model class supplied through response_format, the response can identify row indexes to remove and columns to drop without regex or string slicing. Apply the returned instructions, then inspect the cleaned DataFrame. section 6.2.3 section 6.2
A schema is not a substitute for clear instructions or validation. Define every field the workflow expects, state the cleaning or extraction rules, and keep inputs manageable. For record-level cleaning, process rows individually when whole-dataset requests can produce uneven lists or skipped rows; collect results, rebuild the DataFrame, and drop records still missing critical values. Prompts and schemas can then evolve together—for example, by adding flagged_rows or typo-related fields. section 6.4 section 6.2.3
The same pattern supports extraction from variable raw JSON. A model such as ExtractedArticle can specify source, title, short_summary, and publish_date, while a system prompt describes how to obtain each value. Setting response_format to that model creates a reusable wrapper for schema-compliant outputs; max_tokens and temperature further constrain response length and variation for focused production-style tasks. section 8.2.2
Figure 6.2 The data class acts as a contract between the prompt and the model’s response. The prompt defines what kind of output we want, the data class formalizes that structure, and response_format ensures the model returns data in a predictable, usable format. This makes it easy to extract structured results directly from the model without extra parsing.
This diagram shows the division of responsibility: the prompt requests data, the data class formalizes fields, and response_format yields usable structured results. section 6.2.3













