Skip to content
Cloudflare API
Start here
API Reference
AI

Run a Workers AI model

ai.run(strmodel_name, AIRunParams**kwargs) -> AIRunResponse
POST/accounts/{account_id}/ai/run/{model_name}

Runs the Workers AI model specified in the URL path. Send the model’s inputs directly in the request body, without a model/input/options wrapper.

Accepts model-specific JSON or binary input. The response format depends on the model and the requested output.

See the model catalog for supported models and their input formats.

Security
API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
Accepted Permissions (at least one required)
Workers AI WriteWorkers AI Read
ParametersExpand Collapse
account_id: str

Cloudflare account ID used for this AI model request.

model_name: str

Workers AI model identifier, including its namespace and model name.

text: str

The text that you want to classify

minLength1
ReturnsExpand Collapse
AIRunResponse

An array of classification results for the input text

One of the following:
List[TextClassification]

An array of classification results for the input text

label: Optional[str]

The classification label assigned to the text (e.g., ‘POSITIVE’ or ‘NEGATIVE’)

score: Optional[float]

Confidence score indicating the likelihood that the text belongs to the specified label

object

The generated image in PNG format

class Audio: …
audio: Optional[str]

The generated audio in MP3 format, base64-encoded

object

The generated audio in MP3 format

class TextEmbeddings: …
data: Optional[List[List[float]]]

Embeddings of the requested text values

shape: Optional[List[float]]
class AutomaticSpeechRecognition: …
text: str

The transcription

vtt: Optional[str]
word_count: Optional[float]
words: Optional[List[AutomaticSpeechRecognitionWord]]
end: Optional[float]

The ending second when the word completes

start: Optional[float]

The second this word begins in the recording

word: Optional[str]
List[ImageClassification]
label: Optional[str]

The predicted category or class for the input image based on analysis

score: Optional[float]

A confidence value, between 0 and 1, indicating how certain the model is about the predicted label

List[ObjectDetection]

An array of detected objects within the input image

box: Optional[ObjectDetectionBox]

Coordinates defining the bounding box around the detected object

xmax: Optional[float]

The x-coordinate of the bottom-right corner of the bounding box

xmin: Optional[float]

The x-coordinate of the top-left corner of the bounding box

ymax: Optional[float]

The y-coordinate of the bottom-right corner of the bounding box

ymin: Optional[float]

The y-coordinate of the top-left corner of the bounding box

label: Optional[str]

The class label or name of the detected object

score: Optional[float]

Confidence score indicating the likelihood that the detection is correct

class UnionMember8: …
response: str

The generated text response from the model

tool_calls: Optional[List[UnionMember8ToolCall]]

An array of tool calls requests made during the response generation

arguments: Optional[object]

The arguments passed to be passed to the tool call request

name: Optional[str]

The name of the tool to be called

usage: Optional[UnionMember8Usage]

Usage statistics for the inference request

completion_tokens: Optional[float]

Total number of tokens in output

prompt_tokens: Optional[float]

Total number of tokens in input

total_tokens: Optional[float]

Total number of input and output tokens

object
class Translation: …
translated_text: Optional[str]

The translated text in the target language

class Summarization: …
summary: Optional[str]

The summarized version of the input text

class ImageToText: …
description: Optional[str]
class ImageTextToText: …
description: Optional[str]
class MultimodalEmbeddings: …
data: Optional[List[List[float]]]
shape: Optional[List[float]]

Run a Workers AI model

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.ai.run(
    model_name="@cf/meta/llama-3.1-8b-instruct",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    text="x",
)
print(response)
{
  "result": [
    {
      "label": "label",
      "score": 0
    }
  ]
}
Returns Examples
{
  "result": [
    {
      "label": "label",
      "score": 0
    }
  ]
}