Structured Outputs & Tool Calling

​

Choose an API format

​

JSON Mode

{
  "model": "gpt-5.6-terra",
  "messages": [
    {
      "role": "user",
      "content": "Return a JSON object with city and weather."
    }
  ],
  "response_format": { "type": "json_object" }
}

​

Complete a tool call

1. Send messages plus tool definitions.
2. Read the model response for tool_calls, function_call, Anthropic tool_use, or Gemini function call parts.
3. Execute the tool in your own backend.
4. Append the tool result in the same API format.
5. Continue the conversation until the model returns a final answer.

​

Chat Completions Example

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {
        "role": "user",
        "content": "Extract name and email as JSON. If needed, look up the customer."
      }
    ],
    "response_format": { "type": "json_object" },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_customer",
          "description": "Look up a customer by email",
          "parameters": {
            "type": "object",
            "properties": {
              "email": { "type": "string" }
            },
            "required": ["email"]
          }
        }
      }
    ]
  }'

​

Write a useful schema

• Keep schemas small and explicit. Large nested schemas add tokens and reduce reliability.
• Prefer required fields for values your product cannot continue without.
• Use enums for closed sets that your UI or backend depends on.
• Include examples in the prompt when the model struggles with a shape.
• If a field is not supported, remove it or use an API format that documents it.

​

Before executing a tool

• Record the API format, model, tool names, and schema field names.
• Validate tool arguments before executing any side effect.
• Apply your own permission checks before tool execution.
• Make tool execution idempotent when a client retry can repeat the same tool call.
• Do not log secrets returned by tools into model-visible messages.

​

API Reference