--- title: Run a Workers AI model --- [Skip to content](#_top) [API Reference](https://developers.cloudflare.com/api/python) [AI](https://developers.cloudflare.com/api/python/resources/ai) Copy Markdown Open in **Claude**Open in **ChatGPT**Open in **Cursor** --- **Copy Markdown****View as Markdown** # 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](https://developers.cloudflare.com/workers-ai/models/) 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 Write``Workers AI Read` ##### ParametersExpand Collapse account\_id: str Cloudflare account ID used for this AI model request. [Link to this property](<#(resource)%20ai%20%3E%20(method)%20run%20%3E%20(params)%200%20%3E%20(param)%20account_id%20%3E%20(schema)>) model\_name: str Workers AI model identifier, including its namespace and model name. [Link to this property](<#(resource)%20ai%20%3E%20(method)%20run%20%3E%20(params)%200%20%3E%20(param)%20model_name%20%3E%20(schema)>) text: str The text that you want to classify minLength1 [Link to this property](<#(resource)%20ai%20%3E%20(method)%20run%20%3E%20(params)%200%20%3E%20(param)%20text%20%3E%20(schema)>) ##### 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’) Link to this property score: Optional\[float] Confidence score indicating the likelihood that the text belongs to the specified label Link to this property
Link to this property object The generated image in PNG format Link to this property
class Audio: … audio: Optional\[str] The generated audio in MP3 format, base64-encoded Link to this property
Link to this property object The generated audio in MP3 format Link to this property
class TextEmbeddings: … data: Optional\[List\[List\[float]]] Embeddings of the requested text values Link to this property shape: Optional\[List\[float]] Link to this property
Link to this property
class AutomaticSpeechRecognition: … text: str The transcription Link to this property vtt: Optional\[str] Link to this property word\_count: Optional\[float] Link to this property
words: Optional\[List\[AutomaticSpeechRecognitionWord]] end: Optional\[float] The ending second when the word completes Link to this property start: Optional\[float] The second this word begins in the recording Link to this property word: Optional\[str] Link to this property
Link to this property
Link to this property
List\[ImageClassification] label: Optional\[str] The predicted category or class for the input image based on analysis Link to this property score: Optional\[float] A confidence value, between 0 and 1, indicating how certain the model is about the predicted label Link to this property
Link to this property
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 Link to this property xmin: Optional\[float] The x-coordinate of the top-left corner of the bounding box Link to this property ymax: Optional\[float] The y-coordinate of the bottom-right corner of the bounding box Link to this property ymin: Optional\[float] The y-coordinate of the top-left corner of the bounding box Link to this property
Link to this property label: Optional\[str] The class label or name of the detected object Link to this property score: Optional\[float] Confidence score indicating the likelihood that the detection is correct Link to this property
Link to this property
class UnionMember8: … response: str The generated text response from the model Link to this property
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 Link to this property name: Optional\[str] The name of the tool to be called Link to this property
Link to this property
usage: Optional\[UnionMember8Usage] Usage statistics for the inference request completion\_tokens: Optional\[float] Total number of tokens in output Link to this property prompt\_tokens: Optional\[float] Total number of tokens in input Link to this property total\_tokens: Optional\[float] Total number of input and output tokens Link to this property
Link to this property
Link to this property object Link to this property
class Translation: … translated\_text: Optional\[str] The translated text in the target language Link to this property
Link to this property
class Summarization: … summary: Optional\[str] The summarized version of the input text Link to this property
Link to this property
class ImageToText: … description: Optional\[str] Link to this property
Link to this property
class ImageTextToText: … description: Optional\[str] Link to this property
Link to this property
class MultimodalEmbeddings: … data: Optional\[List\[List\[float]]] Link to this property shape: Optional\[List\[float]] Link to this property
Link to this property
[Link to this property](<#(resource)%20ai%20%3E%20(model)%20ai_run_response%20%3E%20(schema)>) ### Run a Workers AI model Python HTTPTypeScriptPythonGoTerraform ``` 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) ``` 200 example ``` { "result": [ { "label": "label", "score": 0 } ] } ``` ##### Returns Examples 200 example ``` { "result": [ { "label": "label", "score": 0 } ] } ```