# Upload and actions (/en/docs/api/compatible/cloudinary/upload)



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](/en/docs/api/native/media/assets#import-file).

[Guide →](/en/docs/developers/services/media/quickstart)

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.

```javascript
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 →](/en/docs/developers/services/media/quickstart)

[Base URL and authentication](/en/docs/api/compatible/cloudinary)

## Upload [#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 [#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 [#response]

#### HTTP 200 [#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 |  |

```bash
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

```json
{
  "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 [#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 [#request-body-1]

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

Returns: `DestroyResult`.

### Response [#response-1]

#### HTTP 200 [#http-200-1]

Successful response.

**application/json**

| Name | Type | Description |
| --- | --- | --- |
| result | string |  |

```bash
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

```json
{
  "result": "ok"
}
```

## Rename [#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 [#request-body-2]

| 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 [#response-2]

#### HTTP 200 [#http-200-2]

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 |  |

```bash
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

```json
{
  "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
}
```

## Tags [#tags]

`POST /cloudinary/v1_1/{library_id}/{resource_type}/tags`

| 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 [#request-body-3]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| public_ids | string[] | yes | Asset public IDs |
| tag | string | no | Tag name |
| command | add / remove / replace / remove_all | yes | Tag or context action |

Returns: `PublicIds`.

### Response [#response-3]

#### HTTP 200 [#http-200-3]

Successful response.

**application/json**

| Name | Type | Description |
| --- | --- | --- |
| public_ids | array<string> |  |

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

HTTP 200

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

## Context [#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 [#request-body-4]

| 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 [#response-4]

#### HTTP 200 [#http-200-4]

Successful response.

**application/json**

| Name | Type | Description |
| --- | --- | --- |
| public_ids | array<string> |  |

```bash
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

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

## Explicit [#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 [#request-body-5]

| 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 [#response-5]

#### HTTP 200 [#http-200-5]

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 |  |

```bash
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

```json
{
  "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 [#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 [#destroyresult]

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

## PublicIds [#publicids]

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

## ChunkPending [#chunkpending]

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

## ChunkComplete [#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 |