--- title: Run a Workers AI model --- [Skip to content](#_top) [API Reference](https://developers.cloudflare.com/api) [AI](https://developers.cloudflare.com/api/resources/ai) Copy Markdown Open in **Claude**Open in **ChatGPT**Open in **Cursor** --- **Copy Markdown****View as Markdown** # Run a Workers AI model 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` ##### P ath ParametersExpand Collapse account\_id: string 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: string 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)>) ##### Body ParametersJSONExpand Collapse
body: optional object {text } or object {prompt, guidance, height, 8 more } or object {prompt, lang } or 12 more One of the following:
TextClassification object {text } text: string The text that you want to classify minLength1 Link to this property
Link to this property
TextToImage object {prompt, guidance, height, 8 more } prompt: string A text description of the image you want to generate minLength1 Link to this property guidance: optional number Controls how closely the generated image should adhere to the prompt; higher values make the image more aligned with the prompt Link to this property height: optional number The height of the generated image in pixels maximum2048 minimum256 Link to this property image: optional array of number For use with img2img tasks. An array of integers that represent the image data constrained to 8-bit unsigned integer values Link to this property image\_b64: optional string For use with img2img tasks. A base64-encoded string of the input image Link to this property mask: optional array of number An array representing An array of integers that represent mask image data for inpainting constrained to 8-bit unsigned integer values Link to this property negative\_prompt: optional string Text describing elements to avoid in the generated image Link to this property num\_steps: optional number The number of diffusion steps; higher values can improve quality but take longer maximum20 Link to this property seed: optional number Random seed for reproducibility of the image generation Link to this property strength: optional number A value between 0 and 1 indicating how strongly to apply the transformation during img2img tasks; lower values make the output closer to the input image Link to this property width: optional number The width of the generated image in pixels maximum2048 minimum256 Link to this property
Link to this property
TextToSpeech object {prompt, lang } prompt: string A text description of the audio you want to generate minLength1 Link to this property lang: optional string The speech language (e.g., ‘en’ for English, ‘fr’ for French). Defaults to ‘en’ if not specified Link to this property
Link to this property
TextEmbeddings object {text }
text: stringor array of string The text to embed One of the following: string The text to embed Link to this property array of string Batch of text values to embed Link to this property
Link to this property
Link to this property
AutomaticSpeechRecognition object {audio, source\_lang, target\_lang } audio: array of number An array of integers that represent the audio data constrained to 8-bit unsigned integer values Link to this property source\_lang: optional string The language of the recorded audio Link to this property target\_lang: optional string The language to translate the transcription into. Currently only English is supported. Link to this property
Link to this property
ImageClassification object {image } image: array of number An array of integers that represent the image data constrained to 8-bit unsigned integer values Link to this property
Link to this property
ObjectDetection object {image } image: optional array of number An array of integers that represent the image data constrained to 8-bit unsigned integer values Link to this property
Link to this property
Prompt object {prompt, frequency\_penalty, lora, 10 more } prompt: string The input text prompt for the model to generate a response. minLength1 Link to this property frequency\_penalty: optional number Decreases the likelihood of the model repeating the same lines verbatim. maximum2 minimum-2 Link to this property lora: optional string Name of the LoRA (Low-Rank Adaptation) model to fine-tune the base model. Link to this property max\_tokens: optional number The maximum number of tokens to generate in the response. Link to this property presence\_penalty: optional number Increases the likelihood of the model introducing new topics. maximum2 minimum-2 Link to this property raw: optional boolean If true, a chat template is not applied and you must adhere to the specific model’s expected formatting. Link to this property repetition\_penalty: optional number Penalty for repeated tokens; higher values discourage repetition. maximum2 minimum0 Link to this property
response\_format: optional object {json\_schema, type } json\_schema: optional unknown Link to this property
type: optional "json\_object"or "json\_schema" One of the following: "json\_object" Link to this property "json\_schema" Link to this property
Link to this property
Link to this property seed: optional number Random seed for reproducibility of the generation. maximum9999999999 minimum1 Link to this property stream: optional boolean If true, the response will be streamed back incrementally using SSE, Server Sent Events. Link to this property temperature: optional number Controls the randomness of the output; higher values produce more random results. maximum5 minimum0 Link to this property top\_k: optional number Limits the AI to choose from the top ‘k’ most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. maximum50 minimum1 Link to this property top\_p: optional number Adjusts the creativity of the AI’s responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. maximum1 minimum0.001 Link to this property
Link to this property
TextGeneration object {messages, frequency\_penalty, functions, 11 more }
messages: array of object {content, role } An array of message objects representing the conversation history.
content: stringor array of object {text, type } The content of the message as a string. One of the following: string The content of the message as a string. Link to this property
array of object {text, type } Array of text content parts. text: optional string Text content Link to this property type: optional string Type of the content (text) Link to this property
Link to this property
Link to this property role: string The role of the message sender (e.g., ‘user’, ‘assistant’, ‘system’, ‘tool’). Link to this property
Link to this property frequency\_penalty: optional number Decreases the likelihood of the model repeating the same lines verbatim. maximum2 minimum-2 Link to this property
functions: optional array of object {code, name } code: string Link to this property name: string Link to this property
Link to this property max\_tokens: optional number The maximum number of tokens to generate in the response. Link to this property presence\_penalty: optional number Increases the likelihood of the model introducing new topics. maximum2 minimum-2 Link to this property raw: optional boolean If true, a chat template is not applied and you must adhere to the specific model’s expected formatting. Link to this property repetition\_penalty: optional number Penalty for repeated tokens; higher values discourage repetition. maximum2 minimum0 Link to this property
response\_format: optional object {json\_schema, type } json\_schema: optional unknown Link to this property
type: optional "json\_object"or "json\_schema" One of the following: "json\_object" Link to this property "json\_schema" Link to this property
Link to this property
Link to this property seed: optional number Random seed for reproducibility of the generation. maximum9999999999 minimum1 Link to this property stream: optional boolean If true, the response will be streamed back incrementally using SSE, Server Sent Events. Link to this property temperature: optional number Controls the randomness of the output; higher values produce more random results. maximum5 minimum0 Link to this property
tools: optional array of object {description, name, parameters } or object {function, type } A list of tools available for the assistant to use. One of the following:
object {description, name, parameters } description: string A brief description of what the tool does. Link to this property name: string The name of the tool. More descriptive the better. Link to this property
parameters: object {properties, type, required } Schema defining the parameters accepted by the tool.
properties: map\[object {description, type } ] Definitions of each parameter. description: string A description of the expected parameter. Link to this property type: string The data type of the parameter. Link to this property
Link to this property type: string The type of the parameters object (usually ‘object’). Link to this property required: optional array of string List of required parameter names. Link to this property
Link to this property
Link to this property
Function object {function, type }
function: object {description, name, parameters } Details of the function tool. description: string A brief description of what the function does. Link to this property name: string The name of the function. Link to this property
parameters: object {properties, type, required } Schema defining the parameters accepted by the function.
properties: map\[object {description, type } ] Definitions of each parameter. description: string A description of the expected parameter. Link to this property type: string The data type of the parameter. Link to this property
Link to this property type: string The type of the parameters object (usually ‘object’). Link to this property required: optional array of string List of required parameter names. Link to this property
Link to this property
Link to this property type: string Specifies the type of tool (e.g., ‘function’). Link to this property
Link to this property
Link to this property top\_k: optional number Limits the AI to choose from the top ‘k’ most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. maximum50 minimum1 Link to this property top\_p: optional number Adjusts the creativity of the AI’s responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. maximum1 minimum0.001 Link to this property
Link to this property
Translation object {target\_lang, text, source\_lang } target\_lang: string The language code to translate the text into (e.g., ‘es’ for Spanish) Link to this property text: string The text to be translated minLength1 Link to this property source\_lang: optional string The language code of the source text (e.g., ‘en’ for English). Defaults to ‘en’ if not specified Link to this property
Link to this property
Summarization object {input\_text, max\_length } input\_text: string The text that you want the model to summarize minLength1 Link to this property max\_length: optional number The maximum length of the generated summary in tokens Link to this property
Link to this property
ImageToText object {image, frequency\_penalty, max\_tokens, 8 more } image: array of number An array of integers that represent the image data constrained to 8-bit unsigned integer values Link to this property frequency\_penalty: optional number Decreases the likelihood of the model repeating the same lines verbatim. Link to this property max\_tokens: optional number The maximum number of tokens to generate in the response. Link to this property presence\_penalty: optional number Increases the likelihood of the model introducing new topics. Link to this property prompt: optional string The input text prompt for the model to generate a response. Link to this property raw: optional boolean If true, a chat template is not applied and you must adhere to the specific model’s expected formatting. Link to this property repetition\_penalty: optional number Penalty for repeated tokens; higher values discourage repetition. Link to this property seed: optional number Random seed for reproducibility of the generation. Link to this property temperature: optional number Controls the randomness of the output; higher values produce more random results. Link to this property top\_k: optional number Limits the AI to choose from the top ‘k’ most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. Link to this property top\_p: optional number Controls the creativity of the AI’s responses by adjusting how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. Link to this property
Link to this property
object {image, prompt, frequency\_penalty, 8 more } image: string Image in base64 encoded format. Link to this property prompt: string The input text prompt for the model to generate a response. minLength1 Link to this property frequency\_penalty: optional number Decreases the likelihood of the model repeating the same lines verbatim. Link to this property ignore\_eos: optional boolean Whether to ignore the EOS token and continue generating tokens after the EOS token is generated. Link to this property max\_tokens: optional number The maximum number of tokens to generate in the response. Link to this property presence\_penalty: optional number Increases the likelihood of the model introducing new topics. Link to this property repetition\_penalty: optional number Penalty for repeated tokens; higher values discourage repetition. Link to this property seed: optional number Random seed for reproducibility of the generation. Link to this property temperature: optional number Controls the randomness of the output; higher values produce more random results. Link to this property top\_k: optional number Limits the AI to choose from the top ‘k’ most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. Link to this property top\_p: optional number Controls the creativity of the AI’s responses by adjusting how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. Link to this property
Link to this property
ImageTextToText object {image, messages, frequency\_penalty, 8 more } image: string Image in base64 encoded format. Link to this property
messages: array of object {content, role } An array of message objects representing the conversation history.
content: stringor array of object {type, image\_url, text } The content of the message as a string. One of the following: string The content of the message as a string. Link to this property
array of object {type, image\_url, text } Array of content parts (text, image\_url, etc.). type: string Type of the content part (e.g. ‘text’, ‘image\_url’). Link to this property
image\_url: optional object {url } Image URL object (when type is ‘image\_url’). url: string Image URI with data (e.g. data:image/jpeg;base64,/9j/…). Link to this property
Link to this property text: optional string Text content (when type is ‘text’). Link to this property
Link to this property
Link to this property role: string The role of the message sender (e.g., ‘user’, ‘assistant’, ‘system’, ‘tool’). Link to this property
Link to this property frequency\_penalty: optional number Decreases the likelihood of the model repeating the same lines verbatim. Link to this property ignore\_eos: optional boolean Whether to ignore the EOS token and continue generating tokens after the EOS token is generated. Link to this property max\_tokens: optional number The maximum number of tokens to generate in the response. Link to this property presence\_penalty: optional number Increases the likelihood of the model introducing new topics. Link to this property repetition\_penalty: optional number Penalty for repeated tokens; higher values discourage repetition. Link to this property seed: optional number Random seed for reproducibility of the generation. Link to this property temperature: optional number Controls the randomness of the output; higher values produce more random results. Link to this property top\_k: optional number Limits the AI to choose from the top ‘k’ most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. Link to this property top\_p: optional number Controls the creativity of the AI’s responses by adjusting how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. Link to this property
Link to this property
MultimodalEmbeddings object {image, text } image: optional string Image in base64 encoded format. minLength1 Link to this property text: optional array of string Link to this property
Link to this property
[Link to this property](<#(resource)%20ai%20%3E%20(method)%20run%20%3E%20(params)%200%20%3E%20(param)%20body%20%3E%20(schema)>) ##### ReturnsExpand Collapse
result: optional array of object {label, score } or stringor object {audio } or 12 more An array of classification results for the input text One of the following:
TextClassification = array of object {label, score } An array of classification results for the input text label: optional string The classification label assigned to the text (e.g., ‘POSITIVE’ or ‘NEGATIVE’) Link to this property score: optional number Confidence score indicating the likelihood that the text belongs to the specified label Link to this property
Link to this property TextToImage = string The generated image in PNG format Link to this property
Audio object {audio } audio: optional string The generated audio in MP3 format, base64-encoded Link to this property
Link to this property string The generated audio in MP3 format Link to this property
TextEmbeddings object {data, shape } data: optional array of array of number Embeddings of the requested text values Link to this property shape: optional array of number Link to this property
Link to this property
AutomaticSpeechRecognition object {text, vtt, word\_count, words } text: string The transcription Link to this property vtt: optional string Link to this property word\_count: optional number Link to this property
words: optional array of object {end, start, word } end: optional number The ending second when the word completes Link to this property start: optional number The second this word begins in the recording Link to this property word: optional string Link to this property
Link to this property
Link to this property
ImageClassification = array of object {label, score } label: optional string The predicted category or class for the input image based on analysis Link to this property score: optional number 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
ObjectDetection = array of object {box, label, score } An array of detected objects within the input image
box: optional object {xmax, xmin, ymax, ymin } Coordinates defining the bounding box around the detected object xmax: optional number The x-coordinate of the bottom-right corner of the bounding box Link to this property xmin: optional number The x-coordinate of the top-left corner of the bounding box Link to this property ymax: optional number The y-coordinate of the bottom-right corner of the bounding box Link to this property ymin: optional number The y-coordinate of the top-left corner of the bounding box Link to this property
Link to this property label: optional string The class label or name of the detected object Link to this property score: optional number Confidence score indicating the likelihood that the detection is correct Link to this property
Link to this property
object {response, tool\_calls, usage } response: string The generated text response from the model Link to this property
tool\_calls: optional array of object {arguments, name } An array of tool calls requests made during the response generation arguments: optional unknown The arguments passed to be passed to the tool call request Link to this property name: optional string The name of the tool to be called Link to this property
Link to this property
usage: optional object {completion\_tokens, prompt\_tokens, total\_tokens } Usage statistics for the inference request completion\_tokens: optional number Total number of tokens in output Link to this property prompt\_tokens: optional number Total number of tokens in input Link to this property total\_tokens: optional number Total number of input and output tokens Link to this property
Link to this property
Link to this property string Link to this property
Translation object {translated\_text } translated\_text: optional string The translated text in the target language Link to this property
Link to this property
Summarization object {summary } summary: optional string The summarized version of the input text Link to this property
Link to this property
ImageToText object {description } description: optional string Link to this property
Link to this property
ImageTextToText object {description } description: optional string Link to this property
Link to this property
MultimodalEmbeddings object {data, shape } data: optional array of array of number Link to this property shape: optional array of number Link to this property
Link to this property
[Link to this property](<#(resource)%20ai%20%3E%20(method)%20run%20%3E%20(network%20schema)%20%3E%20(property)%20result>) ### Run a Workers AI model HTTP HTTPTypeScriptPythonGoTerraform ``` curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai/run/$MODEL_NAME \ -X POST \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` 200 example ``` { "result": [ { "label": "label", "score": 0 } ] } ``` ##### Returns Examples 200 example ``` { "result": [ { "label": "label", "score": 0 } ] } ```