Clef API setup: call Clef-flash with your own key

This guide connects your application to your Cloudflare account. It does not send your key to ClefBench. You need a Cloudflare Account ID, a Workers AI API token and a terminal with curl. A ClefBench subscription is not required for these requests; Cloudflare handles their usage and billing.

Documentation checked October 10, 2026. The examples below are integration examples, not new ClefBench measurements. We have not executed them with your Cloudflare account.

Clef-flash install: hosted access or local weights?

For the hosted API, there is no model package to install: Cloudflare runs the model. Use the request below from your own server or terminal.

If you mean installing the weights on your own GPU, see the official Clef-flash model card. It documents a custom decision head and a Python inference path tested with PyTorch 2.11 and Transformers 5.10.2 on an H200. This is not a claim that an ordinary laptop or a chat-model launcher can serve it unchanged. Check the current model-card instructions for hardware and runtime compatibility before provisioning a machine. We have not validated that local setup.

1. Create credentials in your own Cloudflare account

In the Cloudflare dashboard, open Workers AI, choose Use REST API, and use the Workers AI token template. Save the Account ID as well as the token. Cloudflare's REST setup guide says a manually created token needs both Workers AI Read and Edit permissions.

Keep the token in a server-side secret or your terminal session. Do not put it in browser JavaScript, a public repository or the ClefBench playground. Restrict the token to the account you intend to call.

For the shell examples, set CLOUDFLARE_ACCOUNT_ID and load CLOUDFLARE_API_TOKEN through your secret manager or a private shell prompt. The names here belong to your application; they are not ClefBench configuration fields.

2. Use the decision contract, not chat completions

Clef uses the System One decision contract: a state and a map of typed questions. For direct Cloudflare access, POST to the Workers AI model run endpoint:

https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/cloudflare/clef-flash

The official Clef-flash example requires the short model selector in the body as well. Do not substitute a messages array or call /v1/chat/completions with this body. “Decisions API” describes this typed decision workflow; it does not mean Cloudflare's direct URL is /v1/decisions.

3. Send a complete curl request

This synthetic example asks whether an invoice needs review, which expense category applies, and the review priority. Save it as decision.json:

{
  "model": "clef-flash",
  "state": "A software renewal costs USD 700. The invoice number is missing, but the supplier and bank account are verified.",
  "questions": {
    "review": {
      "type": "noul",
      "instructions": "Does the invoice lack a required invoice number?"
    },
    "category": {
      "type": "choice",
      "instructions": "Which expense category describes the purchase?",
      "criteria": {
        "software": "A license or subscription for software",
        "equipment": "Physical equipment",
        "travel": "Transportation or accommodation"
      }
    },
    "priority": {
      "type": "score",
      "instructions": "Rate the need for manual review using the stated facts.",
      "criteria": [
        "Complete invoice with verified details",
        "Missing administrative detail",
        "Unverified supplier or bank account",
        "Confirmed fraud"
      ]
    }
  }
}

Then run:

curl --fail-with-body --silent --show-error \
  "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/ai/run/@cf/cloudflare/clef-flash" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-binary @decision.json

To call Clef, change both the URL suffix to @cf/cloudflare/clef and the body selector to "model": "clef". Keep the task and questions unchanged when comparing the two. The Clef model reference documents this pairing.

4. Inspect success and the typed answers

The Cloudflare REST response wraps model output in result and includes success, errors and messages. Check HTTP status and success before reading result.answers. Answers use the same IDs you submitted: review, category and priority.

• noul expresses the probability of yes. Choose your own escalation threshold based on the cost of errors.
• choice identifies an option and its distribution. Keep your option IDs stable if downstream code acts on them.
• score describes an ordered scale; an intermediate value is possible. It is not a percentage of confidence.

Do not invent expected probabilities from this example. Record the actual response, then compare it with independently reviewed references. Our recorded Clef example illustrates how to read these fields; its numbers come from a different task and hosting path.

5. Troubleshoot the request

For other failures, keep the HTTP status and error response and consult Workers AI errors. Avoid blindly repeating a paid call when you do not know whether it completed.

Estimate cost and keep evidence

Use the official price calculator for an input-token estimate. It excludes daily free allowances, base plans and taxes; consult Cloudflare billing for your account's actual charges.

Preserve your sample, question definitions, reference answers, model identifier, run date and raw result. For a reusable starting point, download our synthetic benchmark cases, whose references have not received independent second review. The dataset wraps each task in sample; extract sample.state and sample.questions and add the Cloudflare model selector before sending it. Do not POST the whole dataset or a ClefBench copied request unchanged.

Browser user guide · Clef alternatives · Benchmark methodology