Skip to content
Cloudflare API
Start here
API Reference
AI

Run a Workers AI model

client.AI.Run(ctx, modelName, params) (*AIRunResponseUnion, error)
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
modelName string

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

params AIRunParams
AccountID param.Field[string]

Path param: Cloudflare account ID used for this AI model request.

Text param.Field[string]

Body param: The text that you want to classify

minLength1
ReturnsExpand Collapse
type AIRunResponseUnion interface{…}

An array of classification results for the input text

One of the following:
type AIRunResponseTextClassification []AIRunResponseTextClassificationItem

An array of classification results for the input text

Label stringOptional

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

Score float64Optional

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

UnionString
type AIRunResponseAudio struct{…}
Audio stringOptional

The generated audio in MP3 format, base64-encoded

UnionString
type AIRunResponseTextEmbeddings struct{…}
Data [][]float64Optional

Embeddings of the requested text values

Shape []float64Optional
type AIRunResponseAutomaticSpeechRecognition struct{…}
Text string

The transcription

Vtt stringOptional
WordCount float64Optional
Words []AIRunResponseAutomaticSpeechRecognitionWordOptional
End float64Optional

The ending second when the word completes

Start float64Optional

The second this word begins in the recording

Word stringOptional
type AIRunResponseImageClassification []AIRunResponseImageClassificationItem
Label stringOptional

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

Score float64Optional

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

type AIRunResponseObjectDetection []AIRunResponseObjectDetectionItem

An array of detected objects within the input image

Box AIRunResponseObjectDetectionBoxOptional

Coordinates defining the bounding box around the detected object

Xmax float64Optional

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

Xmin float64Optional

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

Ymax float64Optional

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

Ymin float64Optional

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

Label stringOptional

The class label or name of the detected object

Score float64Optional

Confidence score indicating the likelihood that the detection is correct

type AIRunResponseObject struct{…}
Response string

The generated text response from the model

ToolCalls []AIRunResponseObjectToolCallOptional

An array of tool calls requests made during the response generation

Arguments unknownOptional

The arguments passed to be passed to the tool call request

Name stringOptional

The name of the tool to be called

Usage AIRunResponseObjectUsageOptional

Usage statistics for the inference request

CompletionTokens float64Optional

Total number of tokens in output

PromptTokens float64Optional

Total number of tokens in input

TotalTokens float64Optional

Total number of input and output tokens

UnionString
type AIRunResponseTranslation struct{…}
TranslatedText stringOptional

The translated text in the target language

type AIRunResponseSummarization struct{…}
Summary stringOptional

The summarized version of the input text

type AIRunResponseImageToText struct{…}
Description stringOptional
type AIRunResponseImageTextToText struct{…}
Description stringOptional
type AIRunResponseMultimodalEmbeddings struct{…}
Data [][]float64Optional
Shape []float64Optional

Run a Workers AI model

package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/ai"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  response, err := client.AI.Run(
    context.TODO(),
    "@cf/meta/llama-3.1-8b-instruct",
    ai.AIRunParams{
      AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response)
}

{
  "result": [
    {
      "label": "label",
      "score": 0
    }
  ]
}
Returns Examples
{
  "result": [
    {
      "label": "label",
      "score": 0
    }
  ]
}