Return structured output
Every Model says what it Returns: plain text, fields you name, or JSON of any shape. Facet holds every answer to that shape, so your code can parse it the same way every time.
Pick the shape
On the draft, open Returns and choose Text, Fields or JSON:
| Returns | Answers look like | Use it for |
|---|---|---|
| Text | Refund issued on 3 March. |
Rewriting, summaries, replies |
| Fields | {"label": "billing", "urgent": true} |
Labels, extraction, anything your code reads |
| JSON | Any JSON object | Answers whose shape each input sets, such as “pull out whatever fields this form has” |
Describe each field in a few words: Facet uses the description when it writes examples and checks answers. A field can be text, one of a list of values, yes or no, a number, a whole number, a score from 0 to 1, a date and time, a link, or a list of text. Mark a field optional when an answer may leave it out.
Read the answer
The answer is in the message content, as JSON text. Parse it as usual:
import json
reply = client.chat.completions.create(
model="invoice-fields",
messages=[{"role": "user", "content": invoice_text}],
)
fields = json.loads(reply.choices[0].message.content)
print(fields["total"])
const reply = await client.chat.completions.create({
model: "invoice-fields",
messages: [{ role: "user", content: invoiceText }],
});
const fields = JSON.parse(reply.choices[0].message.content ?? "{}");
console.log(fields.total);
You don’t send a response_format: Facet adds the Model’s shape to every call. A Model that returns JSON also takes your own response_format, of type json_object or json_schema, to set the shape for one call; a Text Model takes one too. A Fields Model always answers in its own fields.
Change the shape later
You can add a field to what a Model returns at any time; callers that ignore it keep working. Removing or renaming a field would break callers, so for that make a new Model, with its own name and its own v1 build.
Next steps
- Call a Model: every parameter a call takes
- Write good evals: check the values, not just the shape