workers_ai()

Create a Cloudflare Workers AI model

Factory function to create a Workers AI model instance using Cloudflare’s OpenAI-compatible endpoints.

Signature

def workers_ai(
    model_id: str,
    *,
    api_key: str | None = None,
    account_id: str | None = None,
    base_url: str | None = None,
) -> LanguageModel

Parameters

model_id · str · required

The Workers AI model identifier, usually in Cloudflare’s @cf/... format.

api_key · str

Cloudflare API token. Falls back to CLOUDFLARE_API_TOKEN, CLOUDFLARE_AUTH_TOKEN, or CLOUDFLARE_API_KEY.

account_id · str

Cloudflare account ID. Falls back to CLOUDFLARE_ACCOUNT_ID.

base_url · str

Custom OpenAI-compatible Workers AI base URL. Use this for AI Gateway or other custom routing.

Returns

A LanguageModel instance configured for Workers AI.

Environment

When base_url is not provided, Workers AI requires:

export CLOUDFLARE_ACCOUNT_ID="..."
export CLOUDFLARE_API_TOKEN="..."

Example

from ai_query import generate_text
from ai_query.providers import workers_ai

result = await generate_text(
    model=workers_ai("@cf/moonshotai/kimi-k2.5"),
    prompt="Hello, world!",
)

Embeddings

embedding_model = workers_ai.embedding("@cf/baai/bge-large-en-v1.5")

Notes

• Uses Cloudflare’s OpenAI-compatible /ai/v1/chat/completions and /ai/v1/embeddings endpoints
• Supports tool calling through the same OpenAI-compatible request format used by ai-query’s existing tool loop
• Accepts custom base_url values for AI Gateway or other OpenAI-compatible Workers AI routing