> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forii.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Structured Outputs

> Guaranteed JSON output from chat completions — JSON schema mode and JSON object mode for form digitization, KYC extraction, and data parsing.

Guaranteed JSON output — critical for form digitization, KYC extraction, and data parsing.

## JSON schema mode

Returns JSON that conforms to a specific schema you define. Best for production pipelines where downstream consumers expect a fixed structure.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    response = client.chat.completions.create(
        model="forii/deepseek-v3",
        messages=[{
            "role": "user",
            "content": "Extract: राहुल शर्मा, उम्र 34, मुंबई"
        }],
        response_format={
            "type": "json_schema",
            "json_schema": {
                "name": "person",
                "schema": {
                    "type": "object",
                    "properties": {
                        "name": {"type": "string"},
                        "age": {"type": "integer"},
                        "city": {"type": "string"}
                    },
                    "required": ["name", "age", "city"]
                }
            }
        }
    )

    print(response.choices[0].message.content)
    # {"name": "राहुल शर्मा", "age": 34, "city": "मुंबई"}
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await client.chat.completions.create({
      model: "forii/deepseek-v3",
      messages: [{
        role: "user",
        content: "Extract: राहुल शर्मा, उम्र 34, मुंबई"
      }],
      response_format: {
        type: "json_schema",
        json_schema: {
          name: "person",
          schema: {
            type: "object",
            properties: {
              name: { type: "string" },
              age: { type: "integer" },
              city: { type: "string" }
            },
            required: ["name", "age", "city"]
          }
        }
      }
    });

    console.log(response.choices[0].message.content);
    // {"name": "राहुल शर्मा", "age": 34, "city": "मुंबई"}
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.forii.in/inference/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $FORII_API_KEY" \
      -d '{
        "model": "forii/deepseek-v3",
        "messages": [{"role": "user", "content": "Extract: राहुल शर्मा, उम्र 34, मुंबई"}],
        "response_format": {
          "type": "json_schema",
          "json_schema": {
            "name": "person",
            "schema": {
              "type": "object",
              "properties": {
                "name": {"type": "string"},
                "age": {"type": "integer"},
                "city": {"type": "string"}
              },
              "required": ["name", "age", "city"]
            }
          }
        }
      }'
    ```
  </Tab>
</Tabs>

### Response

```json theme={null}
{
  "id": "chatcmpl-forii-abc123",
  "object": "chat.completion",
  "model": "forii/deepseek-v3",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "{\"name\": \"राहुल शर्मा\", \"age\": 34, \"city\": \"मुंबई\"}"
    },
    "finish_reason": "stop"
  }]
}
```

<Info>
  The `json_schema` mode guarantees the output matches your schema. If the model cannot produce valid JSON matching the schema, it will retry internally. Use this for production pipelines where downstream consumers expect a fixed structure.
</Info>

## JSON object mode

For arbitrary JSON without a specific schema. The model will return valid JSON, but the shape is not guaranteed.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    response = client.chat.completions.create(
        model="forii/deepseek-v3",
        messages=[{"role": "user", "content": "List 3 Indian cities with population"}],
        response_format={"type": "json_object"}
    )

    print(response.choices[0].message.content)
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await client.chat.completions.create({
      model: "forii/deepseek-v3",
      messages: [{ role: "user", content: "List 3 Indian cities with population" }],
      response_format: { type: "json_object" }
    });

    console.log(response.choices[0].message.content);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.forii.in/inference/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $FORII_API_KEY" \
      -d '{
        "model": "forii/deepseek-v3",
        "messages": [{"role": "user", "content": "List 3 Indian cities with population"}],
        "response_format": {"type": "json_object"}
      }'
    ```
  </Tab>
</Tabs>

<Warning>
  With `json_object` mode, you must include "JSON" or "json" in the system or user message, otherwise the request will fail. The model decides the output shape — use `json_schema` mode when you need a guaranteed structure.
</Warning>

## Parameters

| Parameter                            | Type   | Description                                              |
| ------------------------------------ | ------ | -------------------------------------------------------- |
| `response_format.type`               | string | `"json_object"` or `"json_schema"`                       |
| `response_format.json_schema.name`   | string | Schema name (required for `json_schema` mode)            |
| `response_format.json_schema.schema` | object | JSON Schema definition (required for `json_schema` mode) |