# Upload Asset

Uploads a media file (image, video, or audio) to the authenticated user's HeyGen account and returns the asset ID for future use.

<Callout icon="📘" theme="info">
  **Note:**

  * Scroll down to the **Response** section below and expand the status code(s) to view the detailed response schema.
  * Refer to the **RESPONSE** section on the right and choose an example to see how the API response appears for each status code.
</Callout>

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "heygen-upload-api",
    "version": "4.0.8"
  },
  "servers": [
    {
      "url": "https://upload.heygen.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/v1/asset": {
      "post": {
        "summary": "Upload Asset",
        "description": "Easily upload media files to enhance your AI-generated content",
        "operationId": "upload-asset",
        "parameters": [
          {
            "name": "Content-Type",
            "in": "header",
            "description": "MIME type of the file to upload. Must correspond to the file format. Supported MIME types include: <ul> <li><strong>image/png:</strong> Use for PNG images</li> <li><strong>image/jpeg:</strong> Use for JPEG images</li> <li><strong>audio/mpeg:</strong> Use for MP3 audio files</li> <li><strong>video/mp4:</strong> Use for MP4 videos</li> <li><strong>video/webm:</strong> Use for web-native videos</li> </ul> ",
            "schema": {
              "type": "string",
              "enum": [
                "image/png",
                "image/jpeg",
                "video/mp4",
                "video/webm",
                "audio/mpeg"
              ]
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "RAW_BODY": {
                    "type": "string",
                    "description": "Asset file to upload. The file is sent as raw binary data in the request body. _No additional form fields or parameters are required_. ",
                    "format": "binary"
                  }
                },
                "required": [
                  "RAW_BODY"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Asset uploaded successfully - Expand to view the detailed response schema.",
            "content": {
              "application/json": {
                "examples": {
                  "Image File": {
                    "value": {
                      "code": 100,
                      "data": {
                        "id": "9b57y3fb23e149deabe510e68ad5e409",
                        "name": "9b57y3fb23e149deabe510e68ad5e409",
                        "file_type": "image",
                        "folder_id": "",
                        "meta": null,
                        "created_ts": 1759316668,
                        "url": "https://resource2.heygen.ai/image/9b57y3fb23e149deabe510e68ad5e409/original",
                        "image_key": "image/9b57y3fb23e149deabe510e68ad5e409/original"
                      },
                      "msg": null,
                      "message": null
                    },
                    "summary": "Image File"
                  },
                  "Video File": {
                    "summary": "Video File",
                    "value": {
                      "code": 100,
                      "data": {
                        "id": "b942bfe06485a16f9e54288147a214a4",
                        "name": "b942bfe06485a16f9e54288147a214a4",
                        "file_type": "video",
                        "folder_id": "",
                        "meta": null,
                        "created_ts": 1759314556,
                        "url": "https://resource2.heygen.ai/video/b942bfe06485a16f9e54288147a214a4/original",
                        "image_key": null
                      },
                      "msg": null,
                      "message": null
                    }
                  },
                  "Audio File": {
                    "summary": "Audio File",
                    "value": {
                      "code": 100,
                      "data": {
                        "id": "4b0bf12411b54487ba9adf5cfa5e292f",
                        "name": "4b0bf12411b54487ba9adf5cfa5e292f",
                        "file_type": "audio",
                        "folder_id": "",
                        "meta": null,
                        "created_ts": 1759305865,
                        "url": "https://resource2.heygen.ai/audio/4b0bf12411b54487ba9adf5cfa5e292f/original",
                        "image_key": null
                      },
                      "msg": null,
                      "message": null
                    }
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 100,
                      "default": 0,
                      "description": "Status code indicating the result of the API request. A 100 indicates a successful response. Other codes might indicate different types of errors. Refer to the <a href=\"https://docs.heygen.com/reference/errors\" target=\"_blank\">Error Responses</a> for more details."
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "example": "001ae03f3cc7490faa60e154971b1266",
                          "description": "Unique identifier of the uploaded asset. "
                        },
                        "name": {
                          "type": "string",
                          "example": "001ae03f3cc7490faa60e154971b1266",
                          "description": "ID assigned to the uploaded asset. "
                        },
                        "file_type": {
                          "type": "string",
                          "example": "image",
                          "description": "Type of the uploaded asset, for example, `audio`, `video`, or `image`. "
                        },
                        "folder_id": {
                          "type": "string",
                          "example": "",
                          "description": "Unique identifier of the folder that contains the asset. Empty if the asset is not stored in a specific folder. "
                        },
                        "meta": {
                          "type": "string",
                          "description": "Metadata related to the uploaded asset. "
                        },
                        "created_ts": {
                          "type": "integer",
                          "example": 1684922369,
                          "default": 0,
                          "description": "Unix timestamp when the asset was created. "
                        },
                        "url": {
                          "type": "string",
                          "description": "URL to access or download the uploaded file. "
                        },
                        "image_key": {
                          "type": "string",
                          "description": "Image key for image-type assets. Can be used to created uploaded photo avatars. Returns `null` for non-image files. "
                        }
                      },
                      "description": "Contains detailed information about the asset. "
                    },
                    "msg": {
                      "type": "string",
                      "description": "Legacy field for messages. This field is deprecated."
                    },
                    "message": {
                      "type": "string",
                      "description": "New field for messages. Contains human-readable messages explaining the status of the request. In case of errors, it returns an explanation."
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false,
        "x-readme": {}
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```