← Volver a las guías

LLM Structured Output: JSON Mode to Production

What Structured Output Solves

Large language models are excellent at generating useful text, but applications usually need predictable data: an invoice object, a support classification, a product record, or a list of extracted fields. Asking for “valid JSON” helps, but it does not guarantee the required keys, data types, or nesting. Structured output adds a contract between your application and the model.

JSON mode focuses on producing syntactically valid JSON. Schema-based structured output goes further by describing the exact shape of the response. Your production code should still validate the result, because a valid JSON document can contain the wrong values.

Choose a Response Strategy

• JSON prompting: Ask for JSON in the system or user message. This works with almost any model, but reliability is the lowest.
• JSON mode: Request a JSON object through the API. This reduces parsing failures, but usually does not enforce a particular schema.
• Structured outputs: Provide a JSON Schema and, where supported, enable strict schema adherence. This is the best option for typed application data.
• Tool calling: For models or providers that expose schemas through tools, define one tool and treat its arguments as the structured result. This is a common approach with Claude-style APIs.

Make Your First Request

59API provides a compatible API endpoint at https://api.59api.com, so applications using an OpenAI SDK can usually switch by changing the base URL and API key. Create an account, generate a key, and set it as the environment variable OPENAI_API_KEY. Then install the OpenAI package for your language.

In Python, initialize the client with OpenAI(api_key=os.environ["OPENAI_API_KEY"], base_url="https://api.59api.com/v1"). Use a current GPT model available through your account and send a request with response_format set to {"type":"json_object"}. Your prompt must explicitly request a JSON object and describe the expected fields. Without that instruction, some APIs may return an error or an unhelpful response.

A practical request asks for a customer record with name, email, and an integer priority. After receiving the message, read its content and pass it to your JSON parser. Do not extract JSON with regular expressions; parsers correctly handle escaped quotes, arrays, and nested objects.

Move From JSON Mode to a Schema

For a production workflow, define a schema such as an object with required properties name, email, and priority. Set additional properties to false when the provider supports it, and constrain priority with an integer range or enum. This prevents silent changes from becoming downstream bugs.

Keep the schema narrow. A large schema with optional fields, vague descriptions, and deeply nested arrays gives the model more opportunities to produce ambiguous data. Use clear property descriptions, separate extraction from business decisions, and keep fields that your application can actually use.

Validate, Retry, and Observe

• Parse the response with a standard JSON parser.
• Validate it against the same schema using a library such as Pydantic, Zod, or JSON Schema.
• Reject missing, extra, or incorrectly typed fields before writing to a database.
• Retry only transient failures, timeouts, and recoverable validation errors. Include the validation issue in a corrective follow-up request.
• Log model name, latency, token usage, validation failures, and request identifiers without storing sensitive customer content unnecessarily.

Use bounded retries, such as two attempts, and define a fallback for failure: queue the item for review, return a partial result with an explicit status, or use a deterministic parser. Never let an unchecked model response trigger payments, account changes, or destructive actions.

Production Considerations

Test representative edge cases: empty input, non-English text, malformed emails, very long descriptions, conflicting instructions, and missing fields. Verify both valid and invalid outputs. Pin model versions where possible, because model updates can affect borderline cases even when the schema stays unchanged.

Cost and latency matter when structured extraction runs at scale. 59API offers pay-as-you-go access to official-quality Claude models, including Opus, Sonnet, Haiku, and Fable, as well as GPT models, without requiring a large committed spend. Its compatibility with Claude Code, Codex, and OpenAI SDKs makes it practical to test the same workflow across models. Developers can also use its referral rebate to reduce ongoing API costs. For a low-cost starting point, sign up for 59API, point your existing client at the API base URL, and measure quality, latency, and validation rates before selecting a default model.

Precios · Docs