# Classify text and domains into IAB categories with ZeroGPU's API

ZeroGPU's IAB classifiers map page text, or a bare domain name, straight to IAB 1.0 and 2.2 categories and audience segments, each with a confidence score, so the request needs no instructions or labels. Send `model` and `input` to `POST https://agents.zerogpu.ai/zcj/u5ugmc59njn0/zeroclick/v1/responses`. Each call draws its input and output tokens from prepaid Credits at its model's own rate, from $0.02 per million tokens for input on the base text classifier.

## At a glance

- **Endpoint:** `POST https://agents.zerogpu.ai/zcj/u5ugmc59njn0/zeroclick/v1/responses`, one `input` per request
- **Body:** `model` (`zlm-v1-iab-classify-edge`, `zlm-v2-iab-classify-edge-enriched` or `zlm-v1-iab-domain-classifier`) and `input` (the text or the domain)
- **Price:** per input and output token, by model (table below), drawn from the Credits plan
- **Payment:** buy Credits once with `POST https://agents.zerogpu.ai/zcj/u5ugmc59njn0/plans/{planId}/purchase`. Its 402 is the price quote: pay it with a USDC wallet (x402 or MPP) or a card and send the purchase again. Calls then draw on the balance.
- **Access:** `Authorization: Bearer <token>`, the agent credential the storefront issues, or `Authorization: Receipt <receiptId>` from the small anonymous credit
- **Response:** an OpenAI Responses object whose `output[0].content[0].text` is a JSON string holding the scored categories
- **Limits:** `input` is one string of up to 131,072 characters
- **Full purchase flow:** [the buyer skill](https://agents.zerogpu.ai/zcj/u5ugmc59njn0/SKILL.md)

## Choose a classifier

| Your input | `model` | What the parsed text holds |
| --- | --- | --- |
| Page, post or article text | `zlm-v1-iab-classify-edge` | `audience`, `content.iab_1_0`, `content.iab_2_2`, each entry with `name` and `score` |
| The same text, with a fuller profile | `zlm-v2-iab-classify-edge-enriched` | The same lists with ids, codes and tiers, plus `topics`, `keywords` and `user_intent` |
| A domain name only, such as `example.com` | `zlm-v1-iab-domain-classifier` | `audience` with ids and tiers, plus `content.iab_1_0` and `content.iab_2_2`, with no page content needed |

| `model` | Input tokens | Output tokens |
| --- | --- | --- |
| `zlm-v1-iab-classify-edge` | $0.02 per million tokens | $0.05 per million tokens |
| `zlm-v2-iab-classify-edge-enriched` | $0.05 per million tokens | $0.15 per million tokens |
| `zlm-v1-iab-domain-classifier` | $0.02 per million tokens | $0.05 per million tokens |

## Classify a page or a domain

1. Check for existing credit. A 200 lists your plans with `remainingCreditUsd`:

   ```bash
   curl -s https://agents.zerogpu.ai/zcj/u5ugmc59njn0/agent/entitlements -H "Authorization: Bearer $ACCESS_TOKEN"
   ```

   If you have no credential yet, register one through [auth.md](https://agents.zerogpu.ai/zcj/u5ugmc59njn0/auth.md).

2. Buy Credits if the balance is empty. Find the Credits plan's `purchase.url` in [the manifest](https://agents.zerogpu.ai/zcj/u5ugmc59njn0/manifest.json). Set an amount of at least $0.01 on a wallet rail, or $0.50 by card:

   ```bash
   curl -si -X POST "https://agents.zerogpu.ai/zcj/u5ugmc59njn0/plans/{planId}/purchase" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"amountUsd": "<amount>"}'
   ```

   The storefront answers with a 402, the price quote. Settle it on a wallet rail or by card and retry, as [the buyer skill](https://agents.zerogpu.ai/zcj/u5ugmc59njn0/SKILL.md) sets out.

3. Send the text with its `model`:

   ```bash
   curl -s https://agents.zerogpu.ai/zcj/u5ugmc59njn0/zeroclick/v1/responses \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"model": "zlm-v1-iab-classify-edge", "input": "Five easy weeknight pasta recipes that use pantry staples, with tips for cooking with kids and freezing leftovers."}'
   ```

   This example returned a completed response and drew $0.000019 from credit. Its envelope, trimmed, with the `text` string truncated at `…`:

   ```json
   {
     "object": "response",
     "status": "completed",
     "model": "zlm-v1-iab-classify-edge",
     "output": [{"type": "message", "role": "assistant", "content": [
       {"type": "output_text", "text": "{\"audience\":[{\"name\":\"Cooking\",\"score\":0.8555715505452801},{\"name\":\"Parents with…"}
     ]}],
     "usage": {"input_tokens": 29, "output_tokens": 360, "total_tokens": 389}
   }
   ```

   For the enriched profile, send the same body with `"model": "zlm-v2-iab-classify-edge-enriched"`. Its text opens with audience entries that carry `id`, `parent_id` and `tier1_name`, and that example drew $0.00012. For a domain, send `{"model": "zlm-v1-iab-domain-classifier", "input": "allrecipes.com"}`, which drew $0.000019.

4. Parse `output[0].content[0].text` as JSON. The base classifier's text has this shape, with placeholder values:

   ```json
   {"audience": [{"name": "<segment>", "score": 0.0}],
    "content": {"iab_1_0": [{"name": "<category>", "score": 0.0}],
                "iab_2_2": [{"name": "<category>", "score": 0.0}]}}
   ```

   The enriched and domain texts hold the fields the classifier table above lists for them.

5. Read the `zc-billing` response header to see what the call drew: `{"status":"settled","fundingSource":"credit","chargedUsd":"<debit>","remainingCreditUsd":"<balance>"}`.

To try one call without registering, buy the small credit the manifest lists as `purchase.anonymousCredit`, settle its 402 on a wallet rail, and send `Authorization: Receipt <receiptId>` in place of the bearer.

## Read the scores and set a cut-off

| Your system uses | Read |
| --- | --- |
| IAB Content Taxonomy 1.0 | `content.iab_1_0` |
| IAB Content Taxonomy 2.2 | `content.iab_2_2` |
| Audience segments | `audience` |
| Topics, keywords and intent (enriched classifier) | `topics` (`name`, `score`), `keywords`, `user_intent` (`name`, `category`, `score`) |

Every entry comes back with its `score`, and filtering happens in your code. Keep entries at or above the cut-off you choose. A higher cut-off keeps fewer, stronger labels, and a lower one keeps more. Use the same cut-off for every call in a run, and store it with the labels so later runs compare.

## Boundaries

- No `instructions` or `categories` are needed. The model maps `input` to the taxonomy by itself.
- `text.format.type` accepts `text` only. The classification arrives as a JSON string to parse.
- One `input` per request. A list of pages or domains is a series of requests.
- Nothing is charged until you settle the Credits purchase's 402. Unused credit stays on the balance.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `401 bearer_required` | The call carried no credential | Register at [auth.md](https://agents.zerogpu.ai/zcj/u5ugmc59njn0/auth.md), buy Credits, then retry with the bearer |
| `403 plan_required` | The credential holds no plan covering the call | Buy Credits with your bearer, then retry |
| `usage_exhausted` | The Credits balance is used up | `POST https://agents.zerogpu.ai/zcj/u5ugmc59njn0/extend` with `{"amountUsd": "<amount>"}` |
| `receipt_credit_exhausted` | A receipt's credit cannot cover the call | Buy a new receipt, or buy Credits with a credential |
| `400` | Malformed JSON, or a missing `model` or `input` | Fix the body |
| `429` | Rate limit, counted per agent | Wait `retry-after` seconds, then retry |

The [error reference](https://agents.zerogpu.ai/zcj/u5ugmc59njn0/errors.md) lists the rest.

## Frequently asked questions

### Does the IAB classification API need labels or instructions?

No. All three models map the input straight to the IAB Content Taxonomy, so the body is `model` and `input`.

### Which IAB taxonomy versions does each call return?

The text classifiers return categories in both IAB 1.0 and IAB 2.2 in one call, under `content.iab_1_0` and `content.iab_2_2`, along with scored audience segments.

### Can a domain be classified without fetching the page?

Yes. `zlm-v1-iab-domain-classifier` takes a raw domain name as `input` and returns scored audience segments and IAB 1.0 and 2.2 content categories, with no page fetched.

### What does one classification call cost?

Each call is billed by its input and output tokens at the model's rate, drawn from Credits. The base classifier example used 29 input and 360 output tokens and drew $0.000019.

### Is a ZeroGPU API key needed?

No. Calls through the storefront use the agent credential it issues, or a receipt from the anonymous credit.

## Keep reading

- [Buyer skill](https://agents.zerogpu.ai/zcj/u5ugmc59njn0/SKILL.md): the full purchase flow
- [How to pay](https://agents.zerogpu.ai/zcj/u5ugmc59njn0/payment.md): rails, Credits and top-ups
- [Identity](https://agents.zerogpu.ai/zcj/u5ugmc59njn0/auth.md): register and exchange a credential
- [Manifest](https://agents.zerogpu.ai/zcj/u5ugmc59njn0/manifest.json): live plans and prices

---

Updated 2026-10-14. All ZeroGPU guides: https://agents.zerogpu.ai/guides.md. Storefront: https://agents.zerogpu.ai/zcj/u5ugmc59njn0/llms.txt.