Constrained generation

You can use Exxa Batch API to generate data that adheres to a specific JSON schema. This is useful for generating data that is consistent with a known structure, such as generating data for a database, or to convert any existing data (like a resume, a blog post, etc.) to a specific format.

JSON Schema is a very powerful and complete specification, so it is difficult to support all its features. Some of them (like some data types, recursive definitions, etc.) may not be supported yet or not work properly. Do not hesitate to test your schema, and if it does not work, please let us know.

JSON Schema

To use a JSON schema with your request, you need to set the response_format parameter of request_body. You need to set the type to json_schema and provide a JSON schema in the schema sub parameter. It is also required that a name parameter is set. More details are available on the API documentation. In python, you can do this as follows:

{
    "response_format": {
        "type": "json_schema",
        "json_schema": {
            "name": "My User Schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": { "type": "string" },
                    "age": { "type": "integer" },
                    "email": { "type": "string" },
                    "is_active": { "type": "boolean" }
                },
                "required": ["name", "age", "email"]
            }
        }
    }
}

Here's an example of a JSON object that could be generated based on the schema defined above:

{
    "name": "John Smith",
    "age": 32,
    "email": "john.smith@example.com",
    "is_active": true
}

Tips

You don't need to put the json schema in your prompt, however you can put an example of an object that adheres to the schema. It can helps the model to generate objects fitting your needs, in our example the schema only defines that the name is a string, but the prompt will help the model to know that it should generate a first name and a last name.

Full example

Here is a full python example of a request to generate a user that adheres to the schema defined above.

python

import requests
import os

api_key = os.environ["EXXA_API_KEY"]
url = "https://api.withexxa.com/v1/requests"
headers = {"X-API-Key": api_key, "Content-Type": "application/json"}
payload = {
    "request_body": {
        "model": "llama-3.1-8b-instruct-fp16",
        "response_format": {
            "type": "json_schema",
            "json_schema": {
                "schema": {
                    "type": "object",
                    "properties": {
                        "name": { "type": "string" },
                        "age": { "type": "integer" },
                        "email": { "type": "string" },
                        "is_active": { "type": "boolean" }
                    },
                    "required": ["name", "age", "email"]
                }
            }
        },
        "messages": [{"role": "user",
          "content": "Generate in json format a random user that looks like that: { \"name\": \"John Smith\", \"age\": 32, \"email\": \"john.smith@example.com\", \"is_active\": true}"}]
    }
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())