# Images # V1 ## List images `client.Images.V1.List(ctx, params) (*V4PagePagination[V1ListResponse], error)` **get** `/accounts/{account_id}/images/v1` List up to 100 images with one request. Use the optional parameters below to get a specific range of images. ### Parameters - `params V1ListParams` - `AccountID param.Field[string]` Path param: Account identifier tag. - `Creator param.Field[string]` Query param: Internal user ID set within the creator field. Setting to empty string "" will return images where creator field is not set - `Page param.Field[float64]` Query param: Page number of paginated results. - `PerPage param.Field[float64]` Query param: Number of items per page. ### Returns - `type V1ListResponse struct{…}` - `Images []Image` - `ID string` Image unique identifier. - `Creator string` Can set the creator field with an internal user ID. - `Filename string` Image file name. - `Meta unknown` User modifiable key-value store. Can be used for keeping references to another system of record for managing images. Metadata must not exceed 1024 bytes. - `RequireSignedURLs bool` Indicates whether the image can be a accessed only using it's UID. If set to true, a signed token needs to be generated with a signing key to view the image. - `Uploaded Time` When the media item was uploaded. - `Variants []string` Object specifying available variants for an image. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/images" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) page, err := client.Images.V1.List(context.TODO(), images.V1ListParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "images": [ { "id": "id", "creator": "107b9558-dd06-4bbd-5fef-9c2c16bb7900", "filename": "logo.png", "meta": { "key": "value" }, "requireSignedURLs": true, "uploaded": "2014-01-02T02:20:00.123Z", "variants": [ "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/thumbnail", "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/hero", "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/original" ] } ] }, "success": true } ``` ## Image details `client.Images.V1.Get(ctx, imageID, query) (*Image, error)` **get** `/accounts/{account_id}/images/v1/{image_id}` Fetch details for a single image. ### Parameters - `imageID string` Image unique identifier. - `query V1GetParams` - `AccountID param.Field[string]` Account identifier tag. ### Returns - `type Image struct{…}` - `ID string` Image unique identifier. - `Creator string` Can set the creator field with an internal user ID. - `Filename string` Image file name. - `Meta unknown` User modifiable key-value store. Can be used for keeping references to another system of record for managing images. Metadata must not exceed 1024 bytes. - `RequireSignedURLs bool` Indicates whether the image can be a accessed only using it's UID. If set to true, a signed token needs to be generated with a signing key to view the image. - `Uploaded Time` When the media item was uploaded. - `Variants []string` Object specifying available variants for an image. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/images" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) image, err := client.Images.V1.Get( context.TODO(), "image_id", images.V1GetParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", image.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "id", "creator": "107b9558-dd06-4bbd-5fef-9c2c16bb7900", "filename": "logo.png", "meta": { "key": "value" }, "requireSignedURLs": true, "uploaded": "2014-01-02T02:20:00.123Z", "variants": [ "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/thumbnail", "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/hero", "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/original" ] }, "success": true } ``` ## Upload an image `client.Images.V1.New(ctx, params) (*Image, error)` **post** `/accounts/{account_id}/images/v1` Upload an image with up to 10 Megabytes using a single HTTP POST (multipart/form-data) request. An image can be uploaded by sending an image file or passing an accessible to an API url. ### Parameters - `params V1NewParams` - `AccountID param.Field[string]` Path param: Account identifier tag. - `ID param.Field[string]` Body param: An optional custom unique identifier for your image. - `Creator param.Field[string]` Body param: Can set the creator field with an internal user ID. - `File param.Field[Reader]` Body param: An image binary data. Only needed when type is uploading a file. - `Metadata param.Field[unknown]` Body param: User modifiable key-value store. Can use used for keeping references to another system of record for managing images. - `RequireSignedURLs param.Field[bool]` Body param: Indicates whether the image requires a signature token for the access. - `URL param.Field[string]` Body param: A URL to fetch an image from origin. Only needed when type is uploading from a URL. ### Returns - `type Image struct{…}` - `ID string` Image unique identifier. - `Creator string` Can set the creator field with an internal user ID. - `Filename string` Image file name. - `Meta unknown` User modifiable key-value store. Can be used for keeping references to another system of record for managing images. Metadata must not exceed 1024 bytes. - `RequireSignedURLs bool` Indicates whether the image can be a accessed only using it's UID. If set to true, a signed token needs to be generated with a signing key to view the image. - `Uploaded Time` When the media item was uploaded. - `Variants []string` Object specifying available variants for an image. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/images" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) image, err := client.Images.V1.New(context.TODO(), images.V1NewParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", image.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "id", "creator": "107b9558-dd06-4bbd-5fef-9c2c16bb7900", "filename": "logo.png", "meta": { "key": "value" }, "requireSignedURLs": true, "uploaded": "2014-01-02T02:20:00.123Z", "variants": [ "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/thumbnail", "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/hero", "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/original" ] }, "success": true } ``` ## Update image `client.Images.V1.Edit(ctx, imageID, params) (*Image, error)` **patch** `/accounts/{account_id}/images/v1/{image_id}` Update image access control. On access control change, all copies of the image are purged from cache. ### Parameters - `imageID string` Image unique identifier. - `params V1EditParams` - `AccountID param.Field[string]` Path param: Account identifier tag. - `Creator param.Field[string]` Body param: Can set the creator field with an internal user ID. - `Metadata param.Field[unknown]` Body param: User modifiable key-value store. Can be used for keeping references to another system of record for managing images. No change if not specified. - `RequireSignedURLs param.Field[bool]` Body param: Indicates whether the image can be accessed using only its UID. If set to `true`, a signed token needs to be generated with a signing key to view the image. Returns a new UID on a change. No change if not specified. ### Returns - `type Image struct{…}` - `ID string` Image unique identifier. - `Creator string` Can set the creator field with an internal user ID. - `Filename string` Image file name. - `Meta unknown` User modifiable key-value store. Can be used for keeping references to another system of record for managing images. Metadata must not exceed 1024 bytes. - `RequireSignedURLs bool` Indicates whether the image can be a accessed only using it's UID. If set to true, a signed token needs to be generated with a signing key to view the image. - `Uploaded Time` When the media item was uploaded. - `Variants []string` Object specifying available variants for an image. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/images" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) image, err := client.Images.V1.Edit( context.TODO(), "image_id", images.V1EditParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", image.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "id", "creator": "107b9558-dd06-4bbd-5fef-9c2c16bb7900", "filename": "logo.png", "meta": { "key": "value" }, "requireSignedURLs": true, "uploaded": "2014-01-02T02:20:00.123Z", "variants": [ "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/thumbnail", "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/hero", "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/original" ] }, "success": true } ``` ## Delete image `client.Images.V1.Delete(ctx, imageID, body) (*unknown, error)` **delete** `/accounts/{account_id}/images/v1/{image_id}` Delete an image on Cloudflare Images. On success, all copies of the image are deleted and purged from cache. ### Parameters - `imageID string` Image unique identifier. - `body V1DeleteParams` - `AccountID param.Field[string]` Account identifier tag. ### Returns - `type V1DeleteResponseEnvelopeResult interface{…}` - `unknown` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/images" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) v1, err := client.Images.V1.Delete( context.TODO(), "image_id", images.V1DeleteParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", v1) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": {}, "success": true } ``` ## Domain Types ### Image - `type Image struct{…}` - `ID string` Image unique identifier. - `Creator string` Can set the creator field with an internal user ID. - `Filename string` Image file name. - `Meta unknown` User modifiable key-value store. Can be used for keeping references to another system of record for managing images. Metadata must not exceed 1024 bytes. - `RequireSignedURLs bool` Indicates whether the image can be a accessed only using it's UID. If set to true, a signed token needs to be generated with a signing key to view the image. - `Uploaded Time` When the media item was uploaded. - `Variants []string` Object specifying available variants for an image. # Keys ## List Signing Keys `client.Images.V1.Keys.List(ctx, query) (*V1KeyListResponse, error)` **get** `/accounts/{account_id}/images/v1/keys` Lists your signing keys. These can be found on your Cloudflare Images dashboard. ### Parameters - `query V1KeyListParams` - `AccountID param.Field[string]` Account identifier tag. ### Returns - `type V1KeyListResponse struct{…}` - `Keys []Key` - `Name string` Key name. - `Value string` Key value. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/images" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) keys, err := client.Images.V1.Keys.List(context.TODO(), images.V1KeyListParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", keys.Keys) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "keys": [ { "name": "default", "value": "Oix0bbNaT8Rge9PuyxUBrjI6zrgnsyJ5=" } ] }, "success": true } ``` ## Create a new Signing Key `client.Images.V1.Keys.Update(ctx, signingKeyName, body) (*V1KeyUpdateResponse, error)` **put** `/accounts/{account_id}/images/v1/keys/{signing_key_name}` Create a new signing key with specified name. Returns all keys available. ### Parameters - `signingKeyName string` - `body V1KeyUpdateParams` - `AccountID param.Field[string]` Account identifier tag. ### Returns - `type V1KeyUpdateResponse struct{…}` - `Keys []Key` - `Name string` Key name. - `Value string` Key value. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/images" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) key, err := client.Images.V1.Keys.Update( context.TODO(), "someKey", images.V1KeyUpdateParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", key.Keys) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "keys": [ { "name": "default", "value": "Oix0bbNaT8Rge9PuyxUBrjI6zrgnsyJ5=" } ] }, "success": true } ``` ## Delete Signing Key `client.Images.V1.Keys.Delete(ctx, signingKeyName, body) (*V1KeyDeleteResponse, error)` **delete** `/accounts/{account_id}/images/v1/keys/{signing_key_name}` Delete signing key with specified name. Returns all keys available. When last key is removed, a new default signing key will be generated. ### Parameters - `signingKeyName string` - `body V1KeyDeleteParams` - `AccountID param.Field[string]` Account identifier tag. ### Returns - `type V1KeyDeleteResponse struct{…}` - `Keys []Key` - `Name string` Key name. - `Value string` Key value. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/images" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) key, err := client.Images.V1.Keys.Delete( context.TODO(), "someKey", images.V1KeyDeleteParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", key.Keys) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "keys": [ { "name": "default", "value": "Oix0bbNaT8Rge9PuyxUBrjI6zrgnsyJ5=" } ] }, "success": true } ``` ## Domain Types ### Key - `type Key struct{…}` - `Name string` Key name. - `Value string` Key value. # Stats ## Images usage statistics `client.Images.V1.Stats.Get(ctx, query) (*Stat, error)` **get** `/accounts/{account_id}/images/v1/stats` Fetch image statistics details for Cloudflare Images. The returned statistics detail storage usage, including the current image count vs this account's allowance. ### Parameters - `query V1StatGetParams` - `AccountID param.Field[string]` Account identifier tag. ### Returns - `type Stat struct{…}` - `Count StatCount` - `Allowed float64` Cloudflare Images allowed usage. - `Current float64` Cloudflare Images current usage. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/images" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) stat, err := client.Images.V1.Stats.Get(context.TODO(), images.V1StatGetParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", stat.Count) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "count": { "allowed": 100000, "current": 1000 } }, "success": true } ``` ## Domain Types ### Stat - `type Stat struct{…}` - `Count StatCount` - `Allowed float64` Cloudflare Images allowed usage. - `Current float64` Cloudflare Images current usage. # Variants ## List variants `client.Images.V1.Variants.List(ctx, query) (*Variant, error)` **get** `/accounts/{account_id}/images/v1/variants` Lists existing variants. ### Parameters - `query V1VariantListParams` - `AccountID param.Field[string]` Account identifier tag. ### Returns - `type Variant struct{…}` - `Variants VariantVariants` - `Hero VariantVariantsHero` - `ID string` - `Options VariantVariantsHeroOptions` Allows you to define image resizing sizes for different use cases. - `Fit VariantVariantsHeroOptionsFit` The fit property describes how the width and height dimensions should be interpreted. - `const VariantVariantsHeroOptionsFitScaleDown VariantVariantsHeroOptionsFit = "scale-down"` - `const VariantVariantsHeroOptionsFitContain VariantVariantsHeroOptionsFit = "contain"` - `const VariantVariantsHeroOptionsFitCover VariantVariantsHeroOptionsFit = "cover"` - `const VariantVariantsHeroOptionsFitCrop VariantVariantsHeroOptionsFit = "crop"` - `const VariantVariantsHeroOptionsFitPad VariantVariantsHeroOptionsFit = "pad"` - `Height float64` Maximum height in image pixels. - `Metadata VariantVariantsHeroOptionsMetadata` What EXIF data should be preserved in the output image. - `const VariantVariantsHeroOptionsMetadataKeep VariantVariantsHeroOptionsMetadata = "keep"` - `const VariantVariantsHeroOptionsMetadataCopyright VariantVariantsHeroOptionsMetadata = "copyright"` - `const VariantVariantsHeroOptionsMetadataNone VariantVariantsHeroOptionsMetadata = "none"` - `Width float64` Maximum width in image pixels. - `NeverRequireSignedURLs bool` Indicates whether the variant can access an image without a signature, regardless of image access control. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/images" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) variant, err := client.Images.V1.Variants.List(context.TODO(), images.V1VariantListParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", variant.Variants) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "variants": { "hero": { "id": "hero", "options": { "fit": "scale-down", "height": 768, "metadata": "none", "width": 1366 }, "neverRequireSignedURLs": true } } }, "success": true } ``` ## Variant details `client.Images.V1.Variants.Get(ctx, variantID, query) (*V1VariantGetResponse, error)` **get** `/accounts/{account_id}/images/v1/variants/{variant_id}` Fetch details for a single variant. ### Parameters - `variantID string` - `query V1VariantGetParams` - `AccountID param.Field[string]` Account identifier tag. ### Returns - `type V1VariantGetResponse struct{…}` - `Variant V1VariantGetResponseVariant` - `ID string` - `Options V1VariantGetResponseVariantOptions` Allows you to define image resizing sizes for different use cases. - `Fit V1VariantGetResponseVariantOptionsFit` The fit property describes how the width and height dimensions should be interpreted. - `const V1VariantGetResponseVariantOptionsFitScaleDown V1VariantGetResponseVariantOptionsFit = "scale-down"` - `const V1VariantGetResponseVariantOptionsFitContain V1VariantGetResponseVariantOptionsFit = "contain"` - `const V1VariantGetResponseVariantOptionsFitCover V1VariantGetResponseVariantOptionsFit = "cover"` - `const V1VariantGetResponseVariantOptionsFitCrop V1VariantGetResponseVariantOptionsFit = "crop"` - `const V1VariantGetResponseVariantOptionsFitPad V1VariantGetResponseVariantOptionsFit = "pad"` - `Height float64` Maximum height in image pixels. - `Metadata V1VariantGetResponseVariantOptionsMetadata` What EXIF data should be preserved in the output image. - `const V1VariantGetResponseVariantOptionsMetadataKeep V1VariantGetResponseVariantOptionsMetadata = "keep"` - `const V1VariantGetResponseVariantOptionsMetadataCopyright V1VariantGetResponseVariantOptionsMetadata = "copyright"` - `const V1VariantGetResponseVariantOptionsMetadataNone V1VariantGetResponseVariantOptionsMetadata = "none"` - `Width float64` Maximum width in image pixels. - `NeverRequireSignedURLs bool` Indicates whether the variant can access an image without a signature, regardless of image access control. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/images" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) variant, err := client.Images.V1.Variants.Get( context.TODO(), "hero", images.V1VariantGetParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", variant.Variant) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "variant": { "id": "hero", "options": { "fit": "scale-down", "height": 768, "metadata": "none", "width": 1366 }, "neverRequireSignedURLs": true } }, "success": true } ``` ## Create a variant `client.Images.V1.Variants.New(ctx, params) (*V1VariantNewResponse, error)` **post** `/accounts/{account_id}/images/v1/variants` Specify variants that allow you to resize images for different use cases. ### Parameters - `params V1VariantNewParams` - `AccountID param.Field[string]` Path param: Account identifier tag. - `ID param.Field[string]` Body param - `Options param.Field[V1VariantNewParamsOptions]` Body param: Allows you to define image resizing sizes for different use cases. - `Fit V1VariantNewParamsOptionsFit` The fit property describes how the width and height dimensions should be interpreted. - `const V1VariantNewParamsOptionsFitScaleDown V1VariantNewParamsOptionsFit = "scale-down"` - `const V1VariantNewParamsOptionsFitContain V1VariantNewParamsOptionsFit = "contain"` - `const V1VariantNewParamsOptionsFitCover V1VariantNewParamsOptionsFit = "cover"` - `const V1VariantNewParamsOptionsFitCrop V1VariantNewParamsOptionsFit = "crop"` - `const V1VariantNewParamsOptionsFitPad V1VariantNewParamsOptionsFit = "pad"` - `Height float64` Maximum height in image pixels. - `Metadata V1VariantNewParamsOptionsMetadata` What EXIF data should be preserved in the output image. - `const V1VariantNewParamsOptionsMetadataKeep V1VariantNewParamsOptionsMetadata = "keep"` - `const V1VariantNewParamsOptionsMetadataCopyright V1VariantNewParamsOptionsMetadata = "copyright"` - `const V1VariantNewParamsOptionsMetadataNone V1VariantNewParamsOptionsMetadata = "none"` - `Width float64` Maximum width in image pixels. - `NeverRequireSignedURLs param.Field[bool]` Body param: Indicates whether the variant can access an image without a signature, regardless of image access control. ### Returns - `type V1VariantNewResponse struct{…}` - `Variant V1VariantNewResponseVariant` - `ID string` - `Options V1VariantNewResponseVariantOptions` Allows you to define image resizing sizes for different use cases. - `Fit V1VariantNewResponseVariantOptionsFit` The fit property describes how the width and height dimensions should be interpreted. - `const V1VariantNewResponseVariantOptionsFitScaleDown V1VariantNewResponseVariantOptionsFit = "scale-down"` - `const V1VariantNewResponseVariantOptionsFitContain V1VariantNewResponseVariantOptionsFit = "contain"` - `const V1VariantNewResponseVariantOptionsFitCover V1VariantNewResponseVariantOptionsFit = "cover"` - `const V1VariantNewResponseVariantOptionsFitCrop V1VariantNewResponseVariantOptionsFit = "crop"` - `const V1VariantNewResponseVariantOptionsFitPad V1VariantNewResponseVariantOptionsFit = "pad"` - `Height float64` Maximum height in image pixels. - `Metadata V1VariantNewResponseVariantOptionsMetadata` What EXIF data should be preserved in the output image. - `const V1VariantNewResponseVariantOptionsMetadataKeep V1VariantNewResponseVariantOptionsMetadata = "keep"` - `const V1VariantNewResponseVariantOptionsMetadataCopyright V1VariantNewResponseVariantOptionsMetadata = "copyright"` - `const V1VariantNewResponseVariantOptionsMetadataNone V1VariantNewResponseVariantOptionsMetadata = "none"` - `Width float64` Maximum width in image pixels. - `NeverRequireSignedURLs bool` Indicates whether the variant can access an image without a signature, regardless of image access control. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/images" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) variant, err := client.Images.V1.Variants.New(context.TODO(), images.V1VariantNewParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), ID: cloudflare.F("hero"), Options: cloudflare.F(images.V1VariantNewParamsOptions{ Fit: cloudflare.F(images.V1VariantNewParamsOptionsFitScaleDown), Height: cloudflare.F(768.000000), Metadata: cloudflare.F(images.V1VariantNewParamsOptionsMetadataNone), Width: cloudflare.F(1366.000000), }), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", variant.Variant) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "variant": { "id": "hero", "options": { "fit": "scale-down", "height": 768, "metadata": "none", "width": 1366 }, "neverRequireSignedURLs": true } }, "success": true } ``` ## Update a variant `client.Images.V1.Variants.Edit(ctx, variantID, params) (*V1VariantEditResponse, error)` **patch** `/accounts/{account_id}/images/v1/variants/{variant_id}` Updating a variant purges the cache for all images associated with the variant. ### Parameters - `variantID string` - `params V1VariantEditParams` - `AccountID param.Field[string]` Path param: Account identifier tag. - `Options param.Field[V1VariantEditParamsOptions]` Body param: Allows you to define image resizing sizes for different use cases. - `Fit V1VariantEditParamsOptionsFit` The fit property describes how the width and height dimensions should be interpreted. - `const V1VariantEditParamsOptionsFitScaleDown V1VariantEditParamsOptionsFit = "scale-down"` - `const V1VariantEditParamsOptionsFitContain V1VariantEditParamsOptionsFit = "contain"` - `const V1VariantEditParamsOptionsFitCover V1VariantEditParamsOptionsFit = "cover"` - `const V1VariantEditParamsOptionsFitCrop V1VariantEditParamsOptionsFit = "crop"` - `const V1VariantEditParamsOptionsFitPad V1VariantEditParamsOptionsFit = "pad"` - `Height float64` Maximum height in image pixels. - `Metadata V1VariantEditParamsOptionsMetadata` What EXIF data should be preserved in the output image. - `const V1VariantEditParamsOptionsMetadataKeep V1VariantEditParamsOptionsMetadata = "keep"` - `const V1VariantEditParamsOptionsMetadataCopyright V1VariantEditParamsOptionsMetadata = "copyright"` - `const V1VariantEditParamsOptionsMetadataNone V1VariantEditParamsOptionsMetadata = "none"` - `Width float64` Maximum width in image pixels. - `NeverRequireSignedURLs param.Field[bool]` Body param: Indicates whether the variant can access an image without a signature, regardless of image access control. ### Returns - `type V1VariantEditResponse struct{…}` - `Variant V1VariantEditResponseVariant` - `ID string` - `Options V1VariantEditResponseVariantOptions` Allows you to define image resizing sizes for different use cases. - `Fit V1VariantEditResponseVariantOptionsFit` The fit property describes how the width and height dimensions should be interpreted. - `const V1VariantEditResponseVariantOptionsFitScaleDown V1VariantEditResponseVariantOptionsFit = "scale-down"` - `const V1VariantEditResponseVariantOptionsFitContain V1VariantEditResponseVariantOptionsFit = "contain"` - `const V1VariantEditResponseVariantOptionsFitCover V1VariantEditResponseVariantOptionsFit = "cover"` - `const V1VariantEditResponseVariantOptionsFitCrop V1VariantEditResponseVariantOptionsFit = "crop"` - `const V1VariantEditResponseVariantOptionsFitPad V1VariantEditResponseVariantOptionsFit = "pad"` - `Height float64` Maximum height in image pixels. - `Metadata V1VariantEditResponseVariantOptionsMetadata` What EXIF data should be preserved in the output image. - `const V1VariantEditResponseVariantOptionsMetadataKeep V1VariantEditResponseVariantOptionsMetadata = "keep"` - `const V1VariantEditResponseVariantOptionsMetadataCopyright V1VariantEditResponseVariantOptionsMetadata = "copyright"` - `const V1VariantEditResponseVariantOptionsMetadataNone V1VariantEditResponseVariantOptionsMetadata = "none"` - `Width float64` Maximum width in image pixels. - `NeverRequireSignedURLs bool` Indicates whether the variant can access an image without a signature, regardless of image access control. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/images" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) response, err := client.Images.V1.Variants.Edit( context.TODO(), "hero", images.V1VariantEditParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), Options: cloudflare.F(images.V1VariantEditParamsOptions{ Fit: cloudflare.F(images.V1VariantEditParamsOptionsFitScaleDown), Height: cloudflare.F(768.000000), Metadata: cloudflare.F(images.V1VariantEditParamsOptionsMetadataNone), Width: cloudflare.F(1366.000000), }), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.Variant) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "variant": { "id": "hero", "options": { "fit": "scale-down", "height": 768, "metadata": "none", "width": 1366 }, "neverRequireSignedURLs": true } }, "success": true } ``` ## Delete a variant `client.Images.V1.Variants.Delete(ctx, variantID, body) (*unknown, error)` **delete** `/accounts/{account_id}/images/v1/variants/{variant_id}` Deleting a variant purges the cache for all images associated with the variant. ### Parameters - `variantID string` - `body V1VariantDeleteParams` - `AccountID param.Field[string]` Account identifier tag. ### Returns - `type V1VariantDeleteResponseEnvelopeResult interface{…}` - `unknown` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/images" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) variant, err := client.Images.V1.Variants.Delete( context.TODO(), "hero", images.V1VariantDeleteParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", variant) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": {}, "success": true } ``` ## Domain Types ### Variant - `type Variant struct{…}` - `Variants VariantVariants` - `Hero VariantVariantsHero` - `ID string` - `Options VariantVariantsHeroOptions` Allows you to define image resizing sizes for different use cases. - `Fit VariantVariantsHeroOptionsFit` The fit property describes how the width and height dimensions should be interpreted. - `const VariantVariantsHeroOptionsFitScaleDown VariantVariantsHeroOptionsFit = "scale-down"` - `const VariantVariantsHeroOptionsFitContain VariantVariantsHeroOptionsFit = "contain"` - `const VariantVariantsHeroOptionsFitCover VariantVariantsHeroOptionsFit = "cover"` - `const VariantVariantsHeroOptionsFitCrop VariantVariantsHeroOptionsFit = "crop"` - `const VariantVariantsHeroOptionsFitPad VariantVariantsHeroOptionsFit = "pad"` - `Height float64` Maximum height in image pixels. - `Metadata VariantVariantsHeroOptionsMetadata` What EXIF data should be preserved in the output image. - `const VariantVariantsHeroOptionsMetadataKeep VariantVariantsHeroOptionsMetadata = "keep"` - `const VariantVariantsHeroOptionsMetadataCopyright VariantVariantsHeroOptionsMetadata = "copyright"` - `const VariantVariantsHeroOptionsMetadataNone VariantVariantsHeroOptionsMetadata = "none"` - `Width float64` Maximum width in image pixels. - `NeverRequireSignedURLs bool` Indicates whether the variant can access an image without a signature, regardless of image access control. # Blobs ## Base image `client.Images.V1.Blobs.Get(ctx, imageID, query) (*Response, error)` **get** `/accounts/{account_id}/images/v1/{image_id}/blob` Fetch base image. For most images this will be the originally uploaded file. For larger images it can be a near-lossless version of the original. ### Parameters - `imageID string` Image unique identifier. - `query V1BlobGetParams` - `AccountID param.Field[string]` Account identifier tag. ### Returns - `type V1BlobGetResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/images" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) blob, err := client.Images.V1.Blobs.Get( context.TODO(), "image_id", images.V1BlobGetParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", blob) } ``` # V2 ## List images V2 `client.Images.V2.List(ctx, params) (*V2ListResponse, error)` **get** `/accounts/{account_id}/images/v2` List up to 10000 images with up to 1000 results per page. Use the optional parameters below to get a specific range of images. Pagination is supported via continuation_token. **Metadata Filtering (Optional):** You can optionally filter images by custom metadata fields using the `meta.[]=` syntax. **Supported Operators:** - `eq` / `eq:string` / `eq:number` / `eq:boolean` - Exact match - `in` / `in:string` / `in:number` - Match any value in list (pipe-separated) **Metadata Filter Constraints:** - Maximum 5 metadata filters per request - Maximum 5 levels of nesting (e.g., `meta.first.second.third.fourth.fifth`) - Maximum 10 elements for list operators (`in`) - Supports string, number, and boolean value types **Examples:** ``` # List all images /images/v2 # Filter by metadata [eq] /images/v2?meta.status[eq:string]=active # Filter by metadata [in] /images/v2?meta.status[in]=pending|deleted|flagged # Filter by metadata [in:number] /images/v2?meta.ratings[in:number]=4|5 # Filter by nested metadata /images/v2?meta.region.name[eq]=eu-west # Combine metadata filters with creator /images/v2?meta.status[eq]=active&creator=user123 # Multiple metadata filters (AND logic) /images/v2?meta.status[eq]=active&meta.priority[eq:number]=5 ``` ### Parameters - `params V2ListParams` - `AccountID param.Field[string]` Path param: Account identifier tag. - `ContinuationToken param.Field[string]` Query param: Continuation token to fetch next page. Passed as a query param when requesting List V2 api endpoint. - `Creator param.Field[string]` Query param: Internal user ID set within the creator field. Setting to empty string "" will return images where creator field is not set - `Meta param.Field[V2ListParamsMeta]` Query param - `FieldOperator string` Optional metadata filter(s). Multiple filters can be combined with AND logic. **Operators:** - `eq`, `eq:string`, `eq:number`, `eq:boolean` - Exact match - `in`, `in:string`, `in:number` - Match any value in pipe-separated list **Examples:** - `meta.status[eq]=active` - `meta.priority[eq:number]=5` - `meta.enabled[eq:boolean]=true` - `meta.region[in]=us-east|us-west|eu-west` - `PerPage param.Field[float64]` Query param: Number of items per page - `SortOrder param.Field[V2ListParamsSortOrder]` Query param: Sorting order by upload time - `const V2ListParamsSortOrderAsc V2ListParamsSortOrder = "asc"` - `const V2ListParamsSortOrderDesc V2ListParamsSortOrder = "desc"` ### Returns - `type V2ListResponse struct{…}` - `ContinuationToken string` Continuation token to fetch next page. Passed as a query param when requesting List V2 api endpoint. - `Images []Image` - `ID string` Image unique identifier. - `Creator string` Can set the creator field with an internal user ID. - `Filename string` Image file name. - `Meta unknown` User modifiable key-value store. Can be used for keeping references to another system of record for managing images. Metadata must not exceed 1024 bytes. - `RequireSignedURLs bool` Indicates whether the image can be a accessed only using it's UID. If set to true, a signed token needs to be generated with a signing key to view the image. - `Uploaded Time` When the media item was uploaded. - `Variants []string` Object specifying available variants for an image. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/images" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) v2s, err := client.Images.V2.List(context.TODO(), images.V2ListParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", v2s.ContinuationToken) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "continuation_token": "continuation_token", "images": [ { "id": "id", "creator": "107b9558-dd06-4bbd-5fef-9c2c16bb7900", "filename": "logo.png", "meta": { "key": "value" }, "requireSignedURLs": true, "uploaded": "2014-01-02T02:20:00.123Z", "variants": [ "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/thumbnail", "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/hero", "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/original" ] } ] }, "success": true } ``` # Direct Uploads ## Create authenticated direct upload URL V2 `client.Images.V2.DirectUploads.New(ctx, params) (*V2DirectUploadNewResponse, error)` **post** `/accounts/{account_id}/images/v2/direct_upload` Direct uploads allow users to upload images without API keys. A common use case are web apps, client-side applications, or mobile devices where users upload content directly to Cloudflare Images. This method creates a draft record for a future image. It returns an upload URL and an image identifier. To verify if the image itself has been uploaded, send an image details request (accounts/:account_identifier/images/v1/:identifier), and check that the `draft: true` property is not present. ### Parameters - `params V2DirectUploadNewParams` - `AccountID param.Field[string]` Path param: Account identifier tag. - `ID param.Field[string]` Body param: Optional Image Custom ID. Up to 1024 chars. Can include any number of subpaths, and utf8 characters. Cannot start nor end with a / (forward slash). Cannot be a UUID. - `Creator param.Field[string]` Body param: Can set the creator field with an internal user ID. - `Expiry param.Field[Time]` Body param: The date after which the upload will not be accepted. Minimum: Now + 2 minutes. Maximum: Now + 6 hours. - `Metadata param.Field[unknown]` Body param: User modifiable key-value store. Can be used for keeping references to another system of record, for managing images. - `RequireSignedURLs param.Field[bool]` Body param: Indicates whether the image requires a signature token to be accessed. ### Returns - `type V2DirectUploadNewResponse struct{…}` - `ID string` Image unique identifier. - `UploadURL string` The URL the unauthenticated upload can be performed to using a single HTTP POST (multipart/form-data) request. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/images" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) directUpload, err := client.Images.V2.DirectUploads.New(context.TODO(), images.V2DirectUploadNewParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", directUpload.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "id", "uploadURL": "https://upload.imagedelivery.net/FxUufywByo0m2v3xhKSiU8/e22e9e6b-c02b-42fd-c405-6c32af5fe600" }, "success": true } ```