Cookbook
Structured Output
Obtain machine-readable results with JSON mode or tool calling and validate them strictly in application code.
When results feed a database, workflow, or API, do not rely on natural-language formatting. Use JSON mode or tool calling when supported, and validate the result in your application.
JSON mode example
import json
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["APIQIK_API_KEY"],
base_url="https://api.apiqik.com/v1",
)
response = client.chat.completions.create(
model="qwen-turbo",
messages=[
{
"role": "system",
"content": (
"Return only a JSON object with language, sentiment, and summary. "
"sentiment must be positive, neutral, or negative."
),
},
{
"role": "user",
"content": "Review: Integration is easy, but the first response is a little slow.",
},
],
response_format={"type": "json_object"},
temperature=0,
)
data = json.loads(response.choices[0].message.content)
print(data)Confirm model support first. Support for
response_formatdepends on the model. If JSON mode is unavailable, describe the required structure through tool calling.
Required validation
- Catch JSON parsing errors rather than trusting model text directly.
- Check missing fields, types, and enum values.
- Limit string length, array size, and nesting depth.
- Regenerate or request human review for invalid business-critical fields; do not guess defaults.
- Never directly execute model-generated SQL, code, or URLs.
JSON mode or tool calling
| Method | Suitable use | Caution |
|---|---|---|
| JSON mode | One structured result, such as classification, extraction, or configuration. | Parseable JSON still requires field and business validation. |
| Tool calling | Action selection, multiple functions, or workflows. | The model proposes calls; the application decides whether to execute. |
| Prompt-only | Fallback when neither capability is supported. | Less reliable formatting requires stronger parsing and retry handling. |