Upload and actions

The official SDK treats upload("file_…") as a local file path. To import from File Library, use the native endpoint POST /media/v1/libraries/{library_id}/assets/import; see Import file.

Guide →

Upload accepts file bytes, HTTPS URLs, or data URIs. Use video for audio or auto for detection. SDK upload_large sends chunks to the same upload endpoint.

tags may be a comma-separated string, an array, or repeated tags fields (-F tags=a -F tags=b); all three are equivalent. Comma-separated items are trimmed and empty items dropped. Zero-byte files return FILE_EMPTY; images whose dimensions cannot be read return Invalid image file; any other file is accepted as raw.

await new Promise((resolve, reject) => {
  cloudinary.uploader.upload_large("./video.mp4", {
    resource_type: "video",
    chunk_size: 20 * 1024 * 1024,
  }, (error, result) => error ? reject(error) : resolve(result));
});

Chunks share X-Unique-Upload-Id. Content-Range is bytes start-end/total; use -1 for unknown totals until the final chunk. Non-final chunks must be equal-sized and at least 5 MiB. Sessions expire after 24 hours. Intermediate responses contain done=false and upload_id; the final response includes the resource and done=true.

Guide →

Base URL and authentication

Upload

POST /cloudinary/v1_1/{library_id}/{resource_type}/upload

Parameter	Location	Type	Description
library_id	path	string	Library ID
resource_type	path	image / video / raw / auto	image, video (including audio), or raw; auto applies to uploads only, and listing with auto or any other value returns 400
X-Unique-Upload-Id	header	string	Stable identifier shared by every chunk of this upload.
Content-Range	header	string	Chunk byte range: bytes start-end/total; total may be -1 until the final chunk.

Request body

Field	Type	Required	Description
file	string / string	yes	File bytes, HTTPS URL, data URI, or same-account file_…
public_id	string	no	Asset name in delivery URLs; may contain path segments
public_id_prefix	string	no	Path prefix for public_id; a trailing / is optional and exactly one / separates prefix and ID
display_name	string	no	Display name
asset_folder	string	no	Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root
use_filename	boolean	no	Use the file name for public_id
unique_filename	boolean	no	Append a unique suffix
use_filename_as_display_name	boolean	no	Use the file name as display_name
filename_override	string	no	Override the original file name
overwrite	boolean	no	Whether to overwrite a matching public ID
tags	string / string[]	no	Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list
context	string / object	no	Custom text key/value pairs; PATCH replaces the whole map, {} clears it
auto_tagging	number	no	Merge tags meeting the threshold after understanding; 0–1
resource_type	ResourceType / "auto"	no	image, video (including audio), or raw; auto applies to uploads only, and listing with auto or any other value returns 400

Returns: CloudinaryResource.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
asset_id	string
public_id	string
display_name	string
asset_folder	string
resource_type	string
type	string
format	string
version	number
version_id	string
bytes	number
etag	string
width	number
height	number
duration	number
pages	number
is_audio	boolean
original_filename	string
tags	array<string>
context	object
context.custom	object
created_at	string
url	string
secure_url	string
placeholder	boolean
existing	boolean
processing	object
processing.state	string
processing.kinds	object
processing.updated_at	string
done	boolean
upload_id	string

curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/image/upload" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"file":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==","public_id":"walk-lib-r1-MDP-1791733789929-plain","tags":["docs"]}'

HTTP 200

{
  "asset_id": "85b7ef616a8b4719a41777a036ebc1d2",
  "public_id": "walk-lib-r1-MDP-1791733789929-plain",
  "display_name": "walk-lib-r1-MDP-1791733789929-plain",
  "asset_folder": "",
  "resource_type": "image",
  "type": "upload",
  "format": "png",
  "version": 1791733810,
  "version_id": "fdf3c8cd40c2424d86e8397425a69857",
  "bytes": 70,
  "etag": "b357a19c87624c7c4d131aeeb4ae677f",
  "width": 1,
  "height": 1,
  "original_filename": "file",
  "tags": [
    "docs"
  ],
  "created_at": "2026-10-11T15:50:10.842Z",
  "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
  "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
  "placeholder": false
}

Destroy

POST /cloudinary/v1_1/{library_id}/{resource_type}/destroy

Parameter	Location	Type	Description
library_id	path	string	Library ID
resource_type	path	image / video / raw / auto	image, video (including audio), or raw; auto applies to uploads only, and listing with auto or any other value returns 400

Request body

Field	Type	Required	Description
public_id	string	yes	Asset name in delivery URLs; may contain path segments

Returns: DestroyResult.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
result	string

curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/image/destroy" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"public_id":"docs/renamed"}'

HTTP 200

{
  "result": "ok"
}

Rename

POST /cloudinary/v1_1/{library_id}/{resource_type}/rename

Parameter	Location	Type	Description
library_id	path	string	Library ID
resource_type	path	image / video / raw / auto	image, video (including audio), or raw; auto applies to uploads only, and listing with auto or any other value returns 400

Request body

Field	Type	Required	Description
from_public_id	string	yes	Original public ID
to_public_id	string	yes	New public ID
overwrite	boolean	no	Whether to overwrite a matching public ID

Returns: CloudinaryResource.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
asset_id	string
public_id	string
display_name	string
asset_folder	string
resource_type	string
type	string
format	string
version	number
version_id	string
bytes	number
etag	string
width	number
height	number
duration	number
pages	number
is_audio	boolean
original_filename	string
tags	array<string>
context	object
context.custom	object
created_at	string
url	string
secure_url	string
placeholder	boolean
existing	boolean
processing	object
processing.state	string
processing.kinds	object
processing.updated_at	string

curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/image/rename" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"from_public_id":"docs/pixel","to_public_id":"docs/renamed"}'

HTTP 200

{
  "asset_id": "9339cdae93804c0c8c65d5189ef1f646",
  "public_id": "docs/renamed",
  "display_name": "Sample image",
  "asset_folder": "examples",
  "resource_type": "image",
  "type": "upload",
  "format": "png",
  "version": 1791538418,
  "version_id": "35848c1529994e338e7aa634a1c13d9c",
  "bytes": 70,
  "etag": "b357a19c87624c7c4d131aeeb4ae677f",
  "width": 1,
  "height": 1,
  "original_filename": "file",
  "tags": [
    "docs"
  ],
  "context": {
    "custom": {
      "alt": "Sample"
    }
  },
  "created_at": "2026-10-09T09:33:38.899Z",
  "url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/renamed.png",
  "secure_url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/renamed.png",
  "placeholder": false
}

Context

POST /cloudinary/v1_1/{library_id}/{resource_type}/context

Parameter	Location	Type	Description
library_id	path	string	Library ID
resource_type	path	image / video / raw / auto	image, video (including audio), or raw; auto applies to uploads only, and listing with auto or any other value returns 400

Request body

Field	Type	Required	Description
public_ids	string[]	yes	Asset public IDs
context	string / object	no	Custom text key/value pairs; PATCH replaces the whole map, {} clears it
command	add / remove_all	yes	Tag or context action

Returns: PublicIds.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
public_ids	array<string>

curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/image/context" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"public_ids":["docs/pixel"],"context":"alt=Sample","command":"add"}'

HTTP 200

{
  "public_ids": [
    "docs/pixel"
  ]
}

Explicit

POST /cloudinary/v1_1/{library_id}/{resource_type}/explicit

Parameter	Location	Type	Description
library_id	path	string	Library ID
resource_type	path	image / video / raw / auto	image, video (including audio), or raw; auto applies to uploads only, and listing with auto or any other value returns 400

Request body

Field	Type	Required	Description
public_id	string	yes	Asset name in delivery URLs; may contain path segments
tags	string / string[]	no	Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list
context	string / object	no	Custom text key/value pairs; PATCH replaces the whole map, {} clears it

Returns: CloudinaryResource.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
asset_id	string
public_id	string
display_name	string
asset_folder	string
resource_type	string
type	string
format	string
version	number
version_id	string
bytes	number
etag	string
width	number
height	number
duration	number
pages	number
is_audio	boolean
original_filename	string
tags	array<string>
context	object
context.custom	object
created_at	string
url	string
secure_url	string
placeholder	boolean
existing	boolean
processing	object
processing.state	string
processing.kinds	object
processing.updated_at	string

curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/image/explicit" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"public_id":"docs/pixel","tags":["docs"]}'

HTTP 200

{
  "asset_id": "9339cdae93804c0c8c65d5189ef1f646",
  "public_id": "docs/pixel",
  "display_name": "Sample image",
  "asset_folder": "examples",
  "resource_type": "image",
  "type": "upload",
  "format": "png",
  "version": 1791538418,
  "version_id": "35848c1529994e338e7aa634a1c13d9c",
  "bytes": 70,
  "etag": "b357a19c87624c7c4d131aeeb4ae677f",
  "width": 1,
  "height": 1,
  "original_filename": "file",
  "tags": [
    "docs"
  ],
  "context": {
    "custom": {
      "alt": "Sample"
    }
  },
  "created_at": "2026-10-09T09:33:38.899Z",
  "url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/pixel.png",
  "secure_url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/pixel.png",
  "placeholder": false
}

CloudinaryResource

Field	Type	Required	Description
asset_id	AssetId	yes	Asset ID
public_id	string	yes	Asset name in delivery URLs; may contain path segments
display_name	string	yes	Display name
asset_folder	string	yes	Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root
resource_type	ResourceType	yes	image, video (including audio), or raw; auto applies to uploads only, and listing with auto or any other value returns 400
type	DeliveryType	yes	Resource or event type
format	string	yes	File format
version	number	yes	Delivery version
version_id	string	yes	Version identifier
bytes	number	yes	File size in bytes
etag	string	yes	File checksum
width	number	no	Width in pixels
height	number	no	Height in pixels
duration	number	no	Duration in seconds
pages	number	no	Document pages
is_audio	boolean	no	Whether this is audio
original_filename	string	no	Original file name
tags	string[]	yes	Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list
context	object	no	Custom text key/value pairs; PATCH replaces the whole map, {} clears it
created_at	IsoTimestamp	yes	Creation time
url	string	yes	Original-file URL
secure_url	string	yes	HTTPS delivery URL
placeholder	false	yes	Always false
existing	boolean	no	Whether an existing asset was returned without overwrite
processing	Processing	no	Overall and per-kind processing states

DestroyResult

Field	Type	Required	Description
result	ok / not found	yes	Operation result

PublicIds

Field	Type	Required	Description
public_ids	string[]	yes	Asset public IDs

ChunkPending

Field	Type	Required	Description
done	false	yes	Completed count; completion flag for chunk responses
upload_id	string	yes	Chunk session identifier

ChunkComplete

Field	Type	Required	Description
asset_id	AssetId	yes	Asset ID
public_id	string	yes	Asset name in delivery URLs; may contain path segments
display_name	string	yes	Display name
asset_folder	string	yes	Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root
resource_type	ResourceType	yes	image, video (including audio), or raw; auto applies to uploads only, and listing with auto or any other value returns 400
type	DeliveryType	yes	Resource or event type
format	string	yes	File format
version	number	yes	Delivery version
version_id	string	yes	Version identifier
bytes	number	yes	File size in bytes
etag	string	yes	File checksum
width	number	no	Width in pixels
height	number	no	Height in pixels
duration	number	no	Duration in seconds
pages	number	no	Document pages
is_audio	boolean	no	Whether this is audio
original_filename	string	no	Original file name
tags	string[]	yes	Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list
context	object	no	Custom text key/value pairs; PATCH replaces the whole map, {} clears it
created_at	IsoTimestamp	yes	Creation time
url	string	yes	Original-file URL
secure_url	string	yes	HTTPS delivery URL
placeholder	false	yes	Always false
existing	boolean	no	Whether an existing asset was returned without overwrite
processing	Processing	no	Overall and per-kind processing states

Field	Type	Required	Description
done	true	yes	Completed count; completion flag for chunk responses

Upload and actions

Upload

Request body

Response

HTTP 200

Destroy

Request body

Response

HTTP 200

Rename

Request body

Response

HTTP 200

Tags

Request body

Response

HTTP 200

Context

Request body

Response

HTTP 200

Explicit

Request body

Response

HTTP 200

CloudinaryResource

DestroyResult

PublicIds

ChunkPending

ChunkComplete

On this page