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}