Skip to content
Ads API •References / assets / Upload Asset

Upload Asset

Uploads an asset to storage and returns asset metadata. Supports uploads of files up to 20MB in size. Asset type can be either image, audio, or video. See here for detailed list of requirements for audio assets and here for video assets.

Request

  • ad_account_id
    string [uuid]
    Required

    A unique identifier for an Ad Account.

    Example: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a
  • asset_id
    string [uuid]
    Required

    A unique identifier for the entity.

    Example: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a
  • media
    string [binary]
    Required
    Supported content-type(s): image/png, image/jpeg, audio/ogg, audio/mp3, audio/wav, audio/mpeg, audio/x-wav, video/mp4, video/quicktime
  • asset_type
    string
    Required

    The type of asset.

    Allowed values: "AUDIO", "IMAGE", "VIDEO"Example: "IMAGE"

Response

The newly created asset metadata

Will be one of the following:
  • Metadata object for an image asset type.

    • id
      string [uuid]
      Required

      A unique identifier for the entity.

      Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
    • name
      string
      Required

      The name of the asset file.

      Example: "logoImage.png"
    • assetType
      string
      Required
    • status
      string
      Required

      The current status of an asset throughout lifecycle processes.

      Allowed values: "ERROR", "PROCESSING", "READY", "WAITING_UPLOAD"Example: "READY"
    • url
      string [uri]
      Required

      URL of asset. Will be either Google Cloud Storage URL or CDN URL depending on the asset type and the transcoding completion status.

      Example: "https://i.scdn.co/image/123"
    • created_at
      string [date-time]
      Required

      Date the entity was created. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ

      Example: "2026-01-23T04:56:07Z"
    • updated_at
      string [date-time]
      Required

      Date the entity was updated. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ

      Example: "2026-01-23T04:56:07Z"
    • image_type
      string

      The type of image asset.

      Allowed values: "COMPANION", "LOGO", "USER_UPLOADED_IMAGE"Example: "COMPANION"
    • file_type
      string

      The file type of the image asset as defined by the 'file type' specification of the ISO base media file format standard.

      Allowed values: "JPEG", "PNG"Example: "JPEG"
    • aspect_ratio
      number [double]

      The aspect ratio of the asset with double precision.

      Example: 0.5625
    • width
      integer
      Example: 720
    • height
      integer
      Example: 1280
  • Metadata object for an audio asset type.

    • id
      string [uuid]
      Required

      A unique identifier for the entity.

      Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
    • name
      string
      Required

      The name of the asset file.

      Example: "logoImage.png"
    • assetType
      string
      Required
    • status
      string
      Required

      The current status of an asset throughout lifecycle processes.

      Allowed values: "ERROR", "PROCESSING", "READY", "WAITING_UPLOAD"Example: "READY"
    • url
      string [uri]
      Required

      URL of asset. Will be either Google Cloud Storage URL or CDN URL depending on the asset type and the transcoding completion status.

      Example: "https://i.scdn.co/image/123"
    • created_at
      string [date-time]
      Required

      Date the entity was created. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ

      Example: "2026-01-23T04:56:07Z"
    • updated_at
      string [date-time]
      Required

      Date the entity was updated. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ

      Example: "2026-01-23T04:56:07Z"
    • audio_type
      string

      The type of audio asset.

      Allowed values: "BACKGROUND_MUSIC", "STOCK_BACKGROUND_MUSIC", "USER_UPLOADED_AUDIO"Example: "USER_UPLOADED_AUDIO"
    • duration_ms
      integer [int32]

      The duration of the asset in milliseconds. This value is populated as part of asset processing, and will be null until the asset is in ready state.

      Example: 30000
    • file_type
      string

      The file type of the audio asset as defined by the 'file type' specification of the ISO base media file format standard.

      Allowed values: "MP3", "OGG", "WAV"
  • Metadata object for a video asset type.

    • id
      string [uuid]
      Required

      A unique identifier for the entity.

      Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
    • name
      string
      Required

      The name of the asset file.

      Example: "logoImage.png"
    • assetType
      string
      Required
    • status
      string
      Required

      The current status of an asset throughout lifecycle processes.

      Allowed values: "ERROR", "PROCESSING", "READY", "WAITING_UPLOAD"Example: "READY"
    • url
      string [uri]
      Required

      URL of asset. Will be either Google Cloud Storage URL or CDN URL depending on the asset type and the transcoding completion status.

      Example: "https://i.scdn.co/image/123"
    • created_at
      string [date-time]
      Required

      Date the entity was created. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ

      Example: "2026-01-23T04:56:07Z"
    • updated_at
      string [date-time]
      Required

      Date the entity was updated. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ

      Example: "2026-01-23T04:56:07Z"
    • duration_ms
      integer [int32]

      The duration of the asset in milliseconds. This value is populated as part of asset processing, and will be null until the asset is in ready state.

      Example: 30000
    • aspect_ratio
      number [double]

      The aspect ratio of the asset with double precision.

      Example: 0.5625
    • width
      integer
      Example: 720
    • height
      integer
      Example: 1280
    • file_type
      string

      The file type of the video asset as defined by the 'file type' specification of the ISO base media file format standard.

      Allowed values: "MP4", "QUICKTIME"
    • has_audio
      boolean
    • thumbnail_url
      string [uri]

      URL of thumbnail image of the video asset.

      Example: "https://adstudio-video-preview-image.spotifycdn.com/123-preview"

Response sample

{  "id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",  "name": "logoImage.png",  "assetType": "string",  "status": "READY",  "url": "https://i.scdn.co/image/123",  "created_at": "2026-01-23T04:56:07Z",  "updated_at": "2026-01-23T04:56:07Z",  "image_type": "COMPANION",  "file_type": "JPEG",  "aspect_ratio": 0.5625,  "width": 720,  "height": 1280}