Docs
Sign inJoin the waitlist

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

Esc