---
title: "Instructor with an OpenAI-compatible base_url (Pydantic)"
description: "Extract Pydantic objects from BroadNet Inference with Instructor, using from_openai or from_provider with a custom base_url, and pick the right Mode."
url: https://broadrouter.com/guides/instructor-structured-output/
lang: en
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

# Get structured output with Instructor on BroadNet Inference

Updated 2026-11-16

Wrap an OpenAI client that has base\_url https://inference.broadnet.ai/v1 and your BroadNet key with instructor.from\_openai, then call chat.completions.create with response\_model set to your Pydantic class and model set to broadnet/glm-5.3 or broadnet/qwen3.8-27b. Those are the two models BroadNet lists with tools and structured output. Mode.TOOLS is the default; Mode.JSON\_SCHEMA also works.

Instructor is a Python library that turns LLM replies into validated Pydantic objects and can retry when validation fails. It patches the OpenAI client, and its docs cover OpenAI-compatible servers through `base_url`. BroadNet Inference serves chat completions at `https://inference.broadnet.ai/v1`, and lists tools and structured output for GLM 5.3 and Qwen3.8 27B. BroadRouter is BroadNet’s own site; this follows Instructor’s docs as of version 1.17.0.

## Install

```bash
pip install instructor
export BROADNET_API_KEY='your-broadnet-key'
```

## Extract an object

```python
import os
import instructor
from openai import OpenAI
from pydantic import BaseModel

class Invoice(BaseModel):
    vendor: str
    total: float
    currency: str

client = instructor.from_openai(
    OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"]),
    mode=instructor.Mode.TOOLS,
)

invoice = client.chat.completions.create(
    model="broadnet/glm-5.3",
    response_model=Invoice,
    max_tokens=4000,
    messages=[{"role": "user", "content": "Acme Trading invoice, total 1,250.00 SAR"}],
)
print(invoice)
```

Instructor turns `Invoice` into a tool schema, forces the model to call it with `tool_choice`, and validates the arguments. Pass `max_retries` to control how many times it asks again, with the validation error, when the object doesn’t validate.

## Or use from\_provider

```python
pclient = instructor.from_provider(
    "openai/broadnet/glm-5.3",
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
)
invoice = pclient.create(response_model=Invoice, max_tokens=4000,
                         messages=[{"role": "user", "content": "Acme Trading, 1,250.00 SAR"}])
```

The `openai/` part picks the client. The rest, `broadnet/glm-5.3`, is sent as the model ID.

## Which mode

| Mode | What it sends | Use with BroadNet |
| --- | --- | --- |
| `Mode.TOOLS` (default) | A forced tool call with your schema | Yes, on GLM 5.3 or Qwen3.8 27B |
| `Mode.JSON_SCHEMA` | `response_format` of type `json_schema` | Yes, on GLM 5.3 or Qwen3.8 27B |
| `Mode.MD_JSON` | A plain request; JSON parsed from the text | Fallback for other models; test first |
| `Mode.RESPONSES_TOOLS` | The Responses API | No: BroadNet serves chat completions |

## Images

Qwen3.8 27B takes images as well as tools, so it can read a photo or scan straight into your model:

```python
import base64
img = base64.b64encode(open("invoice.jpg", "rb").read()).decode()
invoice = client.chat.completions.create(
    model="broadnet/qwen3.8-27b",
    response_model=Invoice,
    max_tokens=4000,
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Extract the invoice fields."},
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64," + img}},
    ]}],
)
```

On a pay-as-you-go key an image counts as input tokens. See [reading Arabic invoices with vision](https://broadrouter.com/guides/read-arabic-invoices-with-vision/).

## How we tested this

On 2026-11-15 we installed instructor 1.17.0 with openai 3.3.0 in a clean virtual environment and ran the examples above against a local mock server that speaks BroadNet’s chat-completions shape. We read the logged requests. `Mode.TOOLS` sent the schema as a tool with a forced `tool_choice`, `Mode.JSON_SCHEMA` sent a `json_schema` response format, and both returned a valid `Invoice`. `from_provider` sent the model ID unchanged. Our mock doesn’t write free-text JSON, so we did not test `Mode.MD_JSON`, and we did not send the image example. We had no BroadNet key, so we did not test real model output.

## Troubleshooting

-   **Validation retries that never succeed.** Reasoning counts toward `max_tokens` on GLM 5.3 and Qwen3.8 27B. A low limit can cut off the tool arguments. Raise it. [Why answers come back empty](https://broadrouter.com/guides/reasoning-tokens-empty-response/).
-   **400 on the request.** Check you are on GLM 5.3 or Qwen3.8 27B. If a forced `tool_choice` is rejected, try `Mode.JSON_SCHEMA`.
-   **401.** The key is wrong, expired or out of allowance.
-   **404.** `base_url` must end in `/v1`. GLM 5.3 and Qwen3.8 27B need a top-up; the $5 credit doesn’t cover them.
-   **429 in batch extraction.** A pay-as-you-go key allows 30 requests a minute and 4 in flight. Each validation retry is another request. See [errors and retries](https://broadrouter.com/guides/errors-and-retries/).

## Terms in this guide

[Pay-as-you-go](https://broadrouter.com/glossary/pay-as-you-go/)

Pay-as-you-go is a pricing model in which you pay only for what you use, metered per unit such as tokens, requests or audio minutes, with no subscription or minimum commitment. Most LLM APIs bill this way, from a prepaid balance or a periodic invoice.

[Chat Completions API](https://broadrouter.com/glossary/chat-completions-api/)

The Chat Completions API is OpenAI's HTTP endpoint, POST /v1/chat/completions, that takes a model name and a list of role-tagged messages and returns the model's next message. Its request and response shape became the common format that OpenAI-compatible providers and SDKs reuse.

[Token](https://broadrouter.com/glossary/token/)

A token is the unit of text a language model reads and writes: a word, part of a word, a punctuation mark or a byte sequence produced by the model's tokenizer. LLM APIs count, limit and usually bill usage in tokens.

[Tool calling](https://broadrouter.com/glossary/tool-calling/)

Tool calling, also called function calling, is an LLM API feature in which the model returns a structured request to run a function the developer has defined, with JSON arguments. The application runs the function and sends the result back; the model never runs code itself.

[Concurrency](https://broadrouter.com/glossary/concurrency/)

Concurrency is the number of requests a client has in flight at the same time. LLM APIs often cap it per key or plan, separately from requests per minute, because each open request holds GPU capacity until its response has finished.

[Input and output tokens](https://broadrouter.com/glossary/input-and-output-tokens/)

Input tokens are the tokens a language model reads in a request, including the system prompt, conversation history, tool definitions and images. Output tokens are the tokens it generates in reply, including any reasoning. LLM APIs usually price them separately, and output usually costs more.

[Prepaid credit](https://broadrouter.com/glossary/prepaid-credit/)

Prepaid credit is money added to an API account before use. Each request deducts its cost from the balance, and when the balance runs out, metered requests stop until you top up. It caps spend at what you have paid in.

[Rate limit](https://broadrouter.com/glossary/rate-limit/)

A rate limit is a cap an API places on how much a client can use it in a time window, such as requests per minute or tokens per minute. Requests over the limit are refused, usually with HTTP 429 Too Many Requests, until usage falls back under it.

## Questions

### Which Instructor mode should I use with BroadNet?

Mode.TOOLS, the default, on GLM 5.3 or Qwen3.8 27B, which BroadNet lists with tools and structured output. Mode.JSON\_SCHEMA sends a json\_schema response\_format instead. Both produced valid objects in our mock-server test.

### Can I use Mode.RESPONSES\_TOOLS?

No. Instructor's docs say not to pick it unless the server implements the Responses API. BroadNet serves chat completions only.

### Does Instructor work with DeepSeek V4.1 Flash or Gemma on BroadNet?

BroadNet doesn't list tools or structured output for those models. Mode.MD\_JSON asks for JSON in plain text and parses it, which may work, but test it on your own data before relying on it.

### How do I write the model string for from\_provider?

Use openai/broadnet/glm-5.3. Instructor splits off the first segment as the provider, and in our test it sent broadnet/glm-5.3 to the server unchanged.

## Related guides

-   [Use the OpenAI Python SDK with BroadNet Inference](https://broadrouter.com/guides/openai-python-sdk/)
-   [Use Pydantic AI with BroadNet Inference (OpenAICompatibleProvider)](https://broadrouter.com/guides/pydantic-ai-openai-compatible/)
-   [Read Arabic invoices and receipts with a vision model](https://broadrouter.com/guides/read-arabic-invoices-with-vision/)
-   [Why a reasoning model returns an empty answer](https://broadrouter.com/guides/reasoning-tokens-empty-response/)
-   [All tools that work with BroadNet Inference](https://broadrouter.com/integrations/): SDKs, coding agents, chat UIs and automation tools, with exact settings for each

Try it on your real workload. New accounts start with $5 of credit for Gemma and transcription. DeepSeek, GLM and Qwen3.8 need a top-up.

[Get started](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=guides-instructor-structured-output&utm_content=page-cta) ·

**Sources**

-   [Instructor docs, OpenAI and OpenAI-compatible servers (checked 2026-11-15)](https://python.useinstructor.com/integrations/openai/)
-   [PyPI, instructor 1.17.0 (checked 2026-11-15)](https://pypi.org/project/instructor/)
-   [BroadNet Inference API reference (checked 2026-11-15)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=guides-instructor-structured-output&utm_content=sources)
