Media

Media is a single video that can be used to construct Creative. Media objects are owned by an Ad Account and can be used by multiple Creatives simultaneously.

Attributes

Attribute	Description	Required	Possible Values
ad_account_id	Ad Account ID	R
download_link	URL to Media File	READ-ONLY
media_status	Media Status	READ-ONLY	PENDING_UPLOAD, READY
name	Media name	R
type	Media Type	R	VIDEO, IMAGE, LENS_PACKAGE, PLAYABLE
ai_content_source	Attribute indicating if the media contains AI-generated or AI modified content, can be set by user or Snap	O	USER_AI_GEN, SNAP_AI_GENERATED
lens_package_metadata	Metadata for lens media created by Lens Studio, full spec in Lens section	READ-ONLY
media_usages	Array listing the available uses of the Media for Creatives/Dynamic Templates/Lead Gen Forms	READ-ONLY	["OVERLAY_IMAGE","OVERLAY_BUTTON","APP_INSTALL_ICON_LENS", "APP_INSTALL_ICON", "BACKGROUND", "TOP_SNAP", "OVERLAY_FRAME", "PREVIEW_IMAGE","BANNER_MEDIA","PREVIEW_LOGO","PLAYABLE", "APP_END_CARD"]

Media Usages

The below table outlines where the different Media types are used based on their media_usages value.

Usage entity	Description	Section
TOP_SNAP Creative › `top_snap_media_id`	The main full-screen image or video people see when the ad opens. Used by Snap Ads and all their attachment types, Collection Ads and Dynamic Story Ads.	Create a Snap Ad
APP_INSTALL_ICON Creative › `app_install_properties.icon_media_id` and `deep_link_properties.icon_media_id`	The app icon shown on the App Install or Deep Link card at the bottom of a Snap Ad. Square image.	Snap Ad with App Install attachment
APP_INSTALL_ICON_LENS Creative (LENS_APP_INSTALL / LENS_DEEP_LINK) › `app_install_properties.icon_media_id` and `deep_link_properties.icon_media_id`	The app icon shown as the small call to action on a Lens ad. Same idea as APP_INSTALL_ICON, but the image must be smaller (max 256x256 px).	Lens with App Install Attachment
APP_END_CARD Creative › `app_install_properties.ios_app_end_card_media_ids` and `android_app_end_card_media_ids`	Screenshots of the app shown after the Top Snap on an App Install ad. You must set this value yourself when you create the Media.	App End Cards
PLAYABLE Creative › `playable_media_id`	The playable (interactive mini-game) file used in a playable ad. Given to any Media of type PLAYABLE.	Playable Media Properties
PREVIEW_IMAGE Creative (PREVIEW) › `preview_properties.preview_media_id`	The tile image that shows a Story Ad in the Stories / Discover feed.	Preview Media
PREVIEW_LOGO Creative (PREVIEW) › `preview_properties.logo_media_id`	The brand logo placed on top of the Story Ad tile.	Logo Media
BANNER_MEDIA Lead Generation Form › `banner_media_id`	The header banner image at the top of a Lead Generation form.	Header banner image
OVERLAY_BUTTON Creative Element › `button_properties.button_overlay_media_id`	The image on a button tile in the bottom interaction area of Collection and Dynamic Ads.	Creative Elements – Additional Attributes
OVERLAY_IMAGE Dynamic Template › `overlay_specs[].media_id` (type IMAGE)	A small image (for example a logo or badge) placed on top of the product image in a Dynamic Product Ad.	Overlay Attributes
OVERLAY_FRAME Dynamic Template › `overlay_specs[].media_id` (type FRAME)	A frame with a see-through middle, placed over the whole product image in a Dynamic Product Ad.	Overlay Attributes
BACKGROUND Dynamic Template › `background_media_id`	The background image behind the product in a Dynamic Product Ad template. You must set this value yourself when you create the Media.	Dynamic Template Attributes

Create Media

This endpoint will create a Media entity and return an ID to be used when uploading the Media file.

The attribute ai_content_source along with the value USER_AI_GEN can be set by users to self-declare if the Media contains AI-generated or AI modified content. The value SNAP_AI_GENERATED will be applied if the media was generated by a Snap AI workflow, such as Image-to-Video, this value cannot be set via the API, it’s only applied automatically by Snap services.

HTTP Request

POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/media

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Example 1 - Creating a Media entity of the type VIDEO

This request creates a Media entity of the type VIDEO.

curl -X POST  \
  -d '{"media": [{"name":"Media A - Video", "type":"VIDEO","ad_account_id":"8adc3db7-8148-4fbf-999c-8d2266369d74"}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/media

{
  "request_status": "success",
  "request_id": "57b00d1900ff08a0dae50ab27a0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010b",
  "media": [
    {
      "sub_request_status": "success",
      "media": {
        "id": "a7bee653-1865-41cf-8cee-8ab85a205837",
        "updated_at": "2026-08-14T06:18:01.855Z",
        "created_at": "2026-08-14T06:18:01.855Z",
        "name": "Media A - Video",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "VIDEO",
        "media_status": "PENDING_UPLOAD"
      }
    }
  ]
}

Example 2 - Creating a Media entity of the type IMAGE

This request creates a Media entity of the type IMAGE, it also self declares that the Media file contains AI-generated or AI-modified content.

curl -X POST  \
  -d '{"media": [{"name":"AI Generated Image 9:16 - 1080x1920", "type":"IMAGE","ad_account_id":"81225ba6-7559-4000-9663-bace8adff5a1","ai_content_source": "USER_AI_GEN"}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/81225ba6-7559-4000-9663-bace8adff5a1/media

{
  "request_status": "SUCCESS",
  "request_id": "c547e97c-7eb7-4630-b5f0-d14f203c8a33",
  "media": [
    {
      "sub_request_status": "SUCCESS",
      "media": {
        "id": "8a2bc9d7-1301-439d-b5ea-0ecc2bce6954",
        "updated_at": "2026-08-24T11:48:39.357Z",
        "created_at": "2026-08-24T11:48:39.357Z",
        "name": "AI Generated Image 9:16 - 1080x1920",
        "ad_account_id": "81225ba6-7559-4000-9663-bace8adff5a1",
        "type": "IMAGE",
        "media_status": "PENDING_UPLOAD",
        "is_demo_media": false,
        "visibility": "VISIBLE",
        "ai_content_source": "USER_AI_GEN"
      }
    }
  ]
}

Update AI self declaration

This endpoint allows a user to update the ai_content_source of the Media, it can be set to USER_AI_GEN, or it can be removed completely.

HTTP Request

PATCH https://adsapi.snapchat.com/v1/media/ai_content_source

Attributes that can be added/removed

This endpoint can only add/remove a single attribute.

Attribute	Description	Required	Possible values
ai_content_source	Designates whether the Media contains AI derived content	R	USER_AI_GEN

Example 1 - Adding ai_content_source to the Media

This request adds the ai_content_source with the value USER_AI_GEN to the Media.

curl -X PATCH  \
  -d '{"ai_content_source":[{"media_id":"5d72fa3c-a1fc-4215-8de1-b233b8fa1898","ai_content_source":"USER_AI_GEN"}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/media/ai_content_source

{
  "request_status": "SUCCESS",
  "request_id": "3e4e4881-6ca3-4dc9-8a48-c0ae1193669c",
  "ai_content_source": [
    {
      "sub_request_status": "SUCCESS",
      "ai_content_source": {
        "id": "5d72fa3c-a1fc-4215-8de1-b233b8fa1898",
        "media_id": "5d72fa3c-a1fc-4215-8de1-b233b8fa1898",
        "ai_content_source": "USER_AI_GEN"
      }
    }
  ]
}

Example 2 - Removing ai_content_source from the Media

This request is removes the ai_content_source attribute from the Media.

curl -X PATCH  \
  -d '{"ai_content_source":[{"media_id":"7dp72fa3c-a1fc-4215-8de1-b233b8fa1898"}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/media/ai_content_source

{
  "request_status": "SUCCESS",
  "request_id": "3e4e4881-6ca3-4dc9-8a48-c0ae1193669c",
  "ai_content_source": [
    {
      "sub_request_status": "SUCCESS",
      "ai_content_source": {
        "id": "1d72fa3c-a1fc-4215-8de1-b233b8fa1898",
        "media_id": "7dp72fa3c-a1fc-4215-8de1-b233b8fa1898"
      }
    }
  ]
}

Upload Media - Video

Name	Description	Dimensions	File size	File type	Length seconds
Top Snap	All ad formats, Video specs	1080 x 1920 px	32MB max size , up to 1 GB allowed using chunked upload	mp4, mov	min 3 seconds, max 1800 seconds
Long form video* Deprecated	Used for Long form video attachment	min width 1080 px	32MB max size , up to 1 GB allowed using chunked upload	mp4, mov	min 15 seconds

*The Long Form Video format was deprecated on the 1 February 2023

This endpoint receives the actual video data for the media. Snap Inc. hosts all media on behalf of the advertiser.

HTTP Request

POST https://adsapi.snapchat.com/v1/media/{media_id}/upload

Parameters

Parameter	Default	Description
media_id		Media ID

Example - Upload VIDEO file

curl -X POST -H 'content-type: multipart/form-data' -F 'file=@"/files/MOV_1808.mov";filename="MOV_1808.mov"' \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/media/a7bee653-1865-41cf-8cee-8ab85a205837/upload

{
  "result": {
    "id": "a7bee653-1865-41cf-8cee-8ab85a205837",
    "updated_at": "2016-08-14T06:24:28.378Z",
    "created_at": "2016-08-14T06:23:37.086Z",
    "name": "Media A - Video",
    "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
    "type": "VIDEO",
    "media_status": "READY",
    "file_name": "sample.mov"
  },
  "request_status": "success",
  "request_id": "57b00e9a00ff0ccb4293400c840001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010103"
}

Upload Media - Image

Media of the type IMAGE can be used in various different types of Creatives.

Name	Description	Dimensions	File size	File type
Top Snap Image	Used as Top Snap in Snap Ads, IMAGE type top snaps are converted into 5 sec videos and rendered on the client as videos, Top Snap specs	1080 x 1920 px	5 MB max size	PNG, JPG
Background Image	Used as a background image in Dynamic Ads	1080 x 1920 px	2 MB max size	PNG, JPG
App Icon (Snap Ads)	Icon used for Snap Ad with App Install attachment or Deep Link attachment, image shouldn't have any borders or padding, App Install attachment specs , Deep Link attachment specs	aspect ratio 1:1 (square), min 200 x 200 px, max 2000 x 2000 px	-	PNG
App Icon (Lens)	Icon used specifically for the Lens Creatives LENS_APP_INSTALL and LENS_DEEP_LINK, image shouldn't have any borders or padding	256 x 256 px	-	PNG
Preview Image	Used as Thumbnail in Story Ad Creatives, Story Ad specs	aspect ratio 3:5, min 360 x 600 px	2 MB max size	PNG
Logo Image	Used as Logo overlaid on Thumbnail in Story Ad Creatives, Story Ad specs	993 x 284 px
App End Card	Used as images for the App End cards in App Install Ads	1080 x 1920 px or 1920 x 1080 px	1 MB max size	JPG, JPEG, PNG
Audience Filter	Used as Filter, at least 50% of the image must be transparent, Filter specs	1080 x 2340 px	300kb or less	PNG

HTTP Request

POST https://adsapi.snapchat.com/v1/media/{media_id}/upload

Parameters

Parameter	Default	Description
media_id		Media ID

Example - Upload IMAGE file

curl -X POST -H 'content-type: multipart/form-data' -F 'file=@"/files/app_icon.png";filename="app_icon.png"' \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/media/8adc3db7-8148-4fbf-999c-8d2266369d75/upload

{
  "result": {
    "id": "77062ed3-4abf-49a8-ac3f-8157cf14cb41",
    "updated_at": "2017-04-14T19:39:05.969Z",
    "created_at": "2017-04-14T19:19:59.708Z",
    "name": "IMAGE media",
    "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d75",
    "type": "IMAGE",
    "media_status": "READY",
    "file_name": "app_icon.png",
    "download_link": "https://storage.googleapis.com/ad-manager-creatives-production/77062ed3-4abf-49a8-ac3f-8157cf14cb41/7d935b22-eb12-41b8-9e34-713b64f2e3b3.png"
  },
  "request_status": "SUCCESS",
  "request_id": "58f1255800ff0d03cc7c0c03380001737e616473617069736300016275696c642d64373565633561632d312d35382d3100010"
}

Upload Large Media (Chunked)

This endpoint receives the actual video data for the media. Snapchat hosts all media on behalf of the advertiser.

Files larger than 32MB need to be uploaded in chunks. Each chunk has a maximum size of 32MB and there is a limit of 32 chunks. Hence, the maximum size is 1GB.

Split the large file
Initialize a chunked upload request
Get the "add_path", "finalize_path" and "upload_id" from the response, these will be unique to your upload
Upload all parts of the file using the "add_path" , you will need to prepend it with https://adsapi.snapchat.com
Finalize the chunked upload request using the "finalize_path", you will need to prepend it with https://adsapi.snapchat.com

Request and Parameters for INIT

POST https://adsapi.snapchat.com/v1/media/{media_id}/multipart-upload-v2?action=INIT

Parameter	Description
action	INIT (query param)
file_name	File Name
file_size	Total file size in bytes (cannot exceed 1GB)
number_of_parts	Number of parts to expect

Request and Parameters for ADD

POST https://adsapi.snapchat.com + add_path

Parameter	Description
file	File Part
part_number	File part number, used during re-assembly of file
upload_id	Chunked Upload ID from INIT

Request and Parameters for FINALIZE

POST https://adsapi.snapchat.com + finalize_path

Parameter	Description
upload_id	Chunked Upload ID from INIT

1. Split the large file

Example: split -b 2m lfv.mov split_lfv.

2. Initialize a chunked upload request

curl -X POST -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: multipart/form-data" \
  -F "file_name=lfv.mov" \
  -F "file_size=4887527" \
  -F "number_of_parts=3" \
  "https://adsapi.snapchat.com/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=INIT"

3. Extract upload_id, add_path and finalize_path from response:

  {
    "request_status":"SUCCESS",
    "request_id":"57e56c0b00ff0e1b43229b96350001737e616473617069736300016275696c642d62646338336131372d312d31352d3100010109",
    "upload_id":"cffc3975-f2b3-40d2-bf81-f0e7d97b9af5",
    "add_path":"/us/v1/media/7bd44f53-5de7-41c4-90c7-50633e5dbb7e/multipart-upload-v2?action=ADD",
    "finalize_path":"/v1/media/7bd44f53-5de7-41c4-90c7-50633e5dbb7e/multipart-upload-v2?action=FINALIZE"
  }

4. Upload all parts using the add_path prepended with https://adsapi.snapchat.com:

curl -X POST -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: multipart/form-data" \
  -F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
  -F "file=@split_lfv.aa" \
  -F "part_number=1" \
  "https://adsapi.snapchat.com/us/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=ADD"

curl -X POST -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: multipart/form-data" \
  -F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
  -F "file=@split_lfv.ab" \
  -F "part_number=2" \
  "https://adsapi.snapchat.com/us/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=ADD"

curl -X POST -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: multipart/form-data" \
  -F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
  -F "file=@split_lfv.ac" \
  -F "part_number=3" \
  "https://adsapi.snapchat.com/us/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=ADD"


5. Finalize the chunked upload request using finalize_path prepended with https://adsapi.snapchat.com

curl -X POST -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: multipart/form-data" \
  -F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
  "https://adsapi.snapchat.com/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=FINALIZE"

The above command returns JSON structured like this:

{
  "result": {
    "id": "7536bbc5-0074-4dc4-b654-5ba9cd9f9441",
    "updated_at": "2016-09-23T17:59:23.826Z",
    "created_at": "2016-09-23T17:51:07.799Z",
    "name": "Media Chunked - Video",
    "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
    "type": "VIDEO",
    "media_status": "READY",
    "file_name": "lfv.mov",
    "download_link": "https://storage.googleapis.com/ad-manager-creatives-production-us/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/b195bd7c-aa7b-44c4-83a5-2c12e77a8784.mov"
  },
  "request_status": "SUCCESS",
  "request_id": "57e56d7a00ff0b82bd232ea3d40001737e616473617069736300016275696c642d62646338336131372d312d31352d3100010134"
}

Upload Media - Playable

Media of the type PLAYABLE can be used in Creatives of the type APP_INSTALLS, the playable enables users to test out a game before tapping the attachment to install the game.

Name	Description	Dimensions	File size	File type
Playable	The Playable file is a zip file which contains an index.html and a config.json	-	5 MB max size	ZIP

curl -X POST -H 'content-type: multipart/form-data' -F 'file=@"/files/game-demo.zip";filename="game-demo.zip"' \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/media/62ea8c45-0100-453f-86a8-9e0c38ba41fc/upload

The above command returns JSON structured like this:

{
  "result": {
    "id": "62ea8c45-0100-453f-86a8-9e0c38ba41fc",
    "updated_at": "2025-10-17T09:40:52.998Z",
    "created_at": "2025-10-17T09:36:43.993Z",
    "name": "Playable example media",
    "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
    "type": "PLAYABLE",
    "media_status": "READY",
    "file_name": "3f1f06fd-9c9a-4cc4-8196-3b975b3ce788.zip",
    "download_link": "https://storage.googleapis.com/ad-manager-creatives-production-europe/62ea8c45-0100-453f-86a8-9e0c38ba41fc/3f1f06fd-9c9a-4cc4-8196-3b975b3ce788.zip",
    "file_size_in_bytes": 222015,
    "is_demo_media": false,
    "hash": "oIvHwA==",
    "visibility": "VISIBLE",
    "media_usages": ["PLAYABLE"]
  },
  "request_status": "SUCCESS",
  "request_id": "1c040b69-b0b3-4c72-97e5-b50b5a6ea1f1"
}

HTTP Request

POST https://adsapi.snapchat.com/v1/media/{media_id}/upload

Parameters

Parameter	Default	Description
media_id		Media ID

Copy Media

This endpoint allows media owned by an ad account can be copied to another Ad Account. The following criteria must be met:

The ad accounts must be from the same organization.
The user must have read access to the source media.
The user must have write media permission to the destination ad account.
The media must be READY.
The media is a VIDEO or IMAGE, this endpoint does not support Lens Media.

Multiple media can be copied in the same request. All copies in a single request will be made to the same destination ad account ID. The response object will return a list of status in the same order as the request.

This request is not atomic: for example if one of three requested media objects are not in the READY status, the other two will still be copied. In this scenario, the response will return a partial success.

The number of media objects per request is capped at 20.

HTTP Request

POST https://adsapi.snapchat.com/v1/adaccounts/{destination_ad_account_id}/media_copy

Parameters

Parameter	Description
destination_ad_account_id	Ad Account to copy to (query param)
source_ad_account_id	Ad Account to copy from
source_media_id	The ID of the media to be copied

Example request

curl -X POST \
  -d '{"media_copy":[{"source_media_id": "68348746-55c8-4b6e-9993-f72e9286cd42", "source_ad_account_id": "45c14380-0add-483d-94d6-d3110b8fbb7c"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow"
  https://adsapi.snapchat.com/v1/adaccounts/c3ce0c7e-c213-49eb-b12d-e5524dd83336/media_copy

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "220a5ead-74cf-45d7-bd1a-9b8af886079a",
  "media": [
    {
      "sub_request_status": "SUCCESS",
      "media": {
        "id": "68348746-55c8-4b6e-9993-f72e9286cd42",
        "updated_at": "2025-09-29T05:47:47.365Z",
        "created_at": "2025-09-29T05:47:47.365Z",
        "name": "Me at the aquarium.MP4",
        "ad_account_id": "45c14380-0add-483d-94d6-d3110b8fbb7c",
        "type": "VIDEO",
        "media_status": "READY",
        "file_name": "280b0094-9763-4181-8f05-81df893027b9.MP4",
        "download_link": "https://storage.googleapis.com/ad-manager-creatives-production-europe/44f4f6ab-e60f-495c-befb-574304f48d78/sample123r1.MP4",
        "duration_in_seconds": 18.99,
        "video_metadata": {
          "width_px": 1080,
          "height_px": 1920,
          "rotation": null,
          "integrated_loudness": null,
          "true_peak": null
        },
        "file_size_in_bytes": 7462065,
        "is_demo_media": false,
        "hash": "V7q/ww==",
        "visibility": "VISIBLE",
        "media_usages": ["TOP_SNAP"]
      }
    }
  ]
}

Example request for multiple media copies.

curl -X POST \
  -d '{"media_copy":[{"source_media_id": "68aed4c8-7322-44f3-a752-96ae43ae61fd", "source_ad_account_id": "12225ba6-7559-4000-9663-bace8adff5f2"}, {"source_media_id": "dc3dcf41-a015-4701-97b9-4bed2567a307", "source_ad_account_id": "12225ba6-7559-4000-9663-bace8adff5f2"}, {"source_media_id": "6f0cd867-b405-4b27-adad-a8743c768f31", "source_ad_account_id": "22325ba6-7559-4000-9663-bace8adff5f2"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow"
  https://adsapi.snapchat.com/v1/adaccounts/c3ce0c7e-c213-49eb-b12d-e5524dd83336/media_copy

The above command returns JSON structured like this:

{
  "request_status": "PARTIAL",
  "request_id": "7411a239-5d77-4bb3-8593-4ba162b5973e",
  "media": [
    {
      "sub_request_error_reason": "Error code: E7007, message: Media copy is not supported for media that is invalid or not uploaded : [Media copy is not supported for media that is invalid or not uploaded]",
      "sub_request_status": "ERROR"
    },
    {
      "sub_request_status": "SUCCESS",
      "media": {
        "id": "eefaa007-d0a3-4e77-8dca-8f0ba10fdade",
        "updated_at": "2025-09-29T06:14:31.925Z",
        "created_at": "2025-09-29T06:14:31.925Z",
        "name": "IM A TEAPOT.png",
        "ad_account_id": "c3ce0c7e-c213-49eb-b72d-e5524dd83336",
        "type": "IMAGE",
        "media_status": "READY",
        "file_name": "c6a73e68-e885-418d-a241-56b3d9a25e66.png",
        "download_link": "https://storage.googleapis.com/ad-manager-creatives-production-europe/dc3dcf41-a015-4701-97b9-4bed2567a307/error_418.png",
        "image_metadata": {
          "height_px": 200,
          "width_px": 200,
          "image_format": "PNG"
        },
        "file_size_in_bytes": 12091,
        "is_demo_media": false,
        "hash": "uPn1xA==",
        "visibility": "VISIBLE",
        "media_usages": [
          "APP_INSTALL_ICON_LENS",
          "APP_INSTALL_ICON",
          "OVERLAY_BUTTON"
        ]
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "media": {
        "id": "e41809bc-831e-42b9-8008-313a750eb9a9",
        "updated_at": "2025-09-29T06:14:32.223Z",
        "created_at": "2025-09-29T06:14:32.223Z",
        "name": "GHOST.png",
        "ad_account_id": "c3ce0c7e-c213-49eb-b72d-e5524dd83336",
        "type": "IMAGE",
        "media_status": "READY",
        "file_name": "298c8c04-b12e-49c1-adc6-3d7f2f1f05b6.png",
        "download_link": "https://storage.googleapis.com/ad-manager-creatives-production-europe/6f0cd867-b405-4b27-adad-a8743c768f316/snap_logo.png",
        "image_metadata": {
          "height_px": 600,
          "width_px": 600,
          "image_format": "PNG"
        },
        "file_size_in_bytes": 73011,
        "is_demo_media": false,
        "hash": "F9s+vw==",
        "visibility": "VISIBLE",
        "media_usages": ["APP_INSTALL_ICON", "OVERLAY_BUTTON"]
      }
    }
  ]
}

Note the partial success despite the failure of the first copy.

Fetch all Media in an Ad Account

This endpoint retrieves all media entities associated with an ad account.

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/media

Parameters

Parameter	Description	Possible values
ad_account_id	Ad Account ID
sort	Sorts the resulting Media in descending order by when it was created, this parameter can be combined with limit, but cannot be combined with type	created_at-desc
type	The Media type	IMAGE, LENS_PACKAGE, VIDEO

Example - Fetch all Media in an Ad Account

curl "https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/media" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b00ee800ff0a7e553a9389710001737e616473617069736300016275696c642d35396264653638322d312d31312d37000100",
  "media": [
    {
      "sub_request_status": "success",
      "media": {
        "id": "7f65f9ff-63d8-41e7-991a-06b95a1ffbde",
        "updated_at": "2016-08-12T20:39:57.029Z",
        "created_at": "2016-08-12T20:39:57.029Z",
        "name": "Media 2",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "VIDEO",
        "media_status": "PENDING_UPLOAD"
      }
    },
    {
      "sub_request_status": "success",
      "media": {
        "id": "a7bee653-1865-41cf-8cee-8ab85a205837",
        "updated_at": "2016-08-14T06:24:28.378Z",
        "created_at": "2016-08-14T06:23:37.086Z",
        "name": "Media A - Video",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "VIDEO",
        "media_status": "READY",
        "file_name": "sample.mov"
      }
    },
    {
      "sub_request_status": "success",
      "media": {
        "id": "ab32d7e5-1f80-4e1a-a76b-3c543d2b28e4",
        "updated_at": "2016-08-12T17:38:01.918Z",
        "created_at": "2016-08-12T17:36:59.740Z",
        "name": "App Icon",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "IMAGE",
        "media_status": "READY",
        "file_name": "Mobile Strike.png"
      }
    }
  ]
}

Get a Specific Media

curl "https://adsapi.snapchat.com/v1/media/a7bee653-1865-41cf-8cee-8ab85a205837" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b00f5f00ff0bd6909e4148c30001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010102",
  "media": [
    {
      "sub_request_status": "success",
      "media": {
        "id": "a7bee653-1865-41cf-8cee-8ab85a205837",
        "updated_at": "2016-08-14T06:24:28.378Z",
        "created_at": "2016-08-14T06:23:37.086Z",
        "name": "Media A - Video",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "VIDEO",
        "media_status": "READY",
        "file_name": "sample.mov"
      }
    }
  ]
}

This endpoint retrieves a specific media entity.

HTTP Request

GET https://adsapi.snapchat.com/v1/media/{media_id}

URL Parameters

Parameter	Description
ID	The ID of the media to retrieve

Fetch Multiple Media (POST)

This endpoint allows you to request up to 2,000 specific Media from the same Ad Account by using the POST request body.

HTTP Request

POST https://adsapi.snapchat.com/v1/{ad_account_id}/get_media_by_ids

Body Parameters

Parameter	Description
entity_ids	Array of up to 2000 entries of `{"id":"{media_id}"}`

Example - Fetch Multiple Media (POST)

curl -X POST \
  -d '{"entity_ids":[{"id":"e885c77b-5801-4a4a-924f-5a9cad423bf8"},{"id":"180f8de3-0277-4d54-8107-45e1abb560f8"},{"id":"88222363-8385-4553-94c6-9c11b09d8f9f"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/497979f0-ed17-4971-8288-054883f1cbca/get_media_by_ids

The above command fetches three Media and returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "78abbb65-a9ed-404f-95a4-b99447b8dda7",
  "media": [
    {
      "sub_request_status": "SUCCESS",
      "media": {
        "id": "e885c77b-5801-4a4a-924f-5a9cad423bf8",
        "updated_at": "2024-03-27T21:04:04.705Z",
        "created_at": "2024-03-27T21:04:04.705Z",
        "name": "BulkUploadImage1.jpeg",
        "ad_account_id": "497979f0-ed17-4971-8288-054883f1cbca",
        "type": "IMAGE",
        "media_status": "PENDING_UPLOAD",
        "is_demo_media": false,
        "visibility": "VISIBLE"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "media": {
        "id": "180f8de3-0277-4d54-8107-45e1abb560f8",
        "updated_at": "2021-03-30T19:23:25.270Z",
        "created_at": "2021-03-30T19:23:25.270Z",
        "name": "Voyagers_Tile_Logo_Snap.png",
        "ad_account_id": "497979f0-ed17-4971-8288-054883f1cbca",
        "type": "IMAGE",
        "media_status": "PENDING_UPLOAD",
        "is_demo_media": false,
        "visibility": "VISIBLE"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "media": {
        "id": "88222363-8385-4553-94c6-9c11b09d8f9f",
        "updated_at": "2020-08-04T13:26:46.502Z",
        "created_at": "2020-08-04T13:26:46.502Z",
        "name": "IG_STORY_3 (1).jpg",
        "ad_account_id": "497979f0-ed17-4971-8288-054883f1cbca",
        "type": "IMAGE",
        "media_status": "PENDING_UPLOAD",
        "is_demo_media": false,
        "visibility": "VISIBLE"
      }
    }
  ]
}

Get Preview for a Specific Media

curl "https://adsapi.snapchat.com/v1/media/8e781365-ce4c-4336-8c53-f6a1f7c50af1/preview" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5aa8450b00ff00ff741e879aff00580001737e816473617069736300016275696x642d37633033663563332d312d3134392d310001015e",
  "expires_at": "2018-03-14T21:39:23.303Z",
  "link": "https://adsapi.snapchat.com/media/video_preview?media_id=8e781365-ce4c-4336-8c53-f6a1f7c50af1&expires_at=1521063563303&signature=MGQCMA1DRI6uBax3GSq93E8hp5b3P2Ebg0lIlPa8iGML9rs1B9WFmPeHH6ttvx_rmDG5AgIwY0pjIvEEpwOXM8o3h9Hst60DjRN9Mw7am7OmkdrBGfoI4IiHBflv0XpK87Tnb_BE"
}

This endpoint retrieves the preview for a specific media, this request only works on Media which is of the type VIDEO/IMAGE.

HTTP Request

GET https://adsapi.snapchat.com/v1/media/{media_id}/preview

URL Parameters

Parameter	Description
ID	The ID of the media to retrieve, can only be of type VIDEO/IMAGE

Get Thumbnail for a Specific Media

curl "https://adsapi.snapchat.com/v1/media/095a4a6d-01a0-4f6a-8901-41ea38c7a540/thumbnail" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5b99772a00ff06928d3e31e94b0001737e616473617069736300016275696c642d33346634346232622d312d3230302d3200010154",
  "expires_at": "2018-09-13T20:29:30.555Z",
  "link": "https://adsapi.snapchat.com/media/video_thumbnail?media_id=095a4a6d-01b0-4f6c-8901-41ee38c7b540&expires_at=1536870570555&signature=MGQCMBQ_NfJM0yZCrdyLiEon4Lkbei0zFJF2HpLiHa2NvSLV2JyOVhLqHfQgqbDWUuzaCQIwHzPj_ZFtPNk688SoFiKWUIFEKKBMhSm8t4moy9xlfgnoSv-8LMQ1omM_P8QCj7O9"
}

This endpoint retrieves a thumbnail for media of the type VIDEO Thumbnails cannnot be fetched for other Media types (IMAGE, LENS_PACKAGE).

HTTP Request

GET https://adsapi.snapchat.com/v1/media/{media_id}/thumbnail

URL Parameters

Parameter	Description
ID	The ID of the media (type VIDEO) to retrieve a thumbnail from

Get Lens Preview Media

Using the Lens Preview endpoint makes it possible to retrieve Preview media associated with a specific Lens. The Lens preview endpoint only works with media entities where the type is specified as LENS_PACKAGE.

Note that not all Lens Media will have preview resources available, the existence of preview resources depends on when and how the Lens was created.

Lens Preview Attributes

Attribute	Description
icon_url	Logo used for the Lens
preview_video_url	Video capture of the Lens
preview_image_url	Image capture of the Lens
description	Description of Lens

HTTP Request

GET https://adsapi.snapchat.com/v1/media/{media_id}/lens_preview

URL Parameters

Attribute	Description
Media ID	The ID of the media (type LENS_PACKAGE) to retrieve resources from

Example request

This example shows the response of a Lens Media that has preview resources available.

curl "https://adsapi.snapchat.com/v1/media/2f5fa39a-0d15-4f38-b8f7-6b901fc8b847/lens_preview" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "icon_url": "https://lens-storage.storage.googleapis.com/png/f7c87f9743824e668fafa45b3ef318bf",
  "preview_video_url": "https://community-lens.storage.googleapis.com/preview-media/final/90570eb3-15cb-4937-967b-c621a69cf941.mp4",
  "preview_image_url": "https://community-lens.storage.googleapis.com/preview-media/final_poster/90570eb3-15cb-4937-967b-c621a69cf941.jpg",
  "description": "Lens: Spectacles by Snap",
  "request_status": "SUCCESS",
  "request_id": "75b36043-1266-43c5-bfb5-38fea0a973b3"
}

Was this page helpful?

Yes

Attributes​

Media Usages​

Create Media​

HTTP Request​

Parameters​

Example 1 - Creating a Media entity of the type VIDEO​

Example 2 - Creating a Media entity of the type IMAGE​

Update AI self declaration​

HTTP Request​

Attributes that can be added/removed​

Example 1 - Adding ai_content_source to the Media​

Example 2 - Removing ai_content_source from the Media​

Upload Media - Video​

HTTP Request​

Parameters​

Example - Upload VIDEO file​

Upload Media - Image​

HTTP Request​

Parameters​

Example - Upload IMAGE file​

Upload Large Media (Chunked)​

Request and Parameters for INIT​

Request and Parameters for ADD​

Request and Parameters for FINALIZE​

Upload Media - Playable​

HTTP Request​

Parameters​

Copy Media​

HTTP Request​

Parameters​

Example request​

Example request for multiple media copies.​

Fetch all Media in an Ad Account​

HTTP Request​

Parameters​

Example - Fetch all Media in an Ad Account​

Get a Specific Media​

HTTP Request​

URL Parameters​

Fetch Multiple Media (POST)​

HTTP Request​

Body Parameters​

Example - Fetch Multiple Media (POST)​

Get Preview for a Specific Media​

HTTP Request​

URL Parameters​

Get Thumbnail for a Specific Media​

HTTP Request​

URL Parameters​

Get Lens Preview Media​

HTTP Request​

URL Parameters​

Example request​

Attributes

Media Usages

Create Media

HTTP Request

Parameters

Example 1 - Creating a Media entity of the type VIDEO

Example 2 - Creating a Media entity of the type IMAGE

Update AI self declaration

HTTP Request

Attributes that can be added/removed

Example 1 - Adding ai_content_source to the Media

Example 2 - Removing ai_content_source from the Media

Upload Media - Video

HTTP Request

Parameters

Example - Upload VIDEO file

Upload Media - Image

HTTP Request

Parameters

Example - Upload IMAGE file

Upload Large Media (Chunked)

Request and Parameters for INIT

Request and Parameters for ADD

Request and Parameters for FINALIZE

Upload Media - Playable

HTTP Request

Parameters

Copy Media

HTTP Request

Parameters

Example request

Example request for multiple media copies.

Fetch all Media in an Ad Account

HTTP Request

Parameters

Example - Fetch all Media in an Ad Account

Get a Specific Media

HTTP Request

URL Parameters

Fetch Multiple Media (POST)

HTTP Request

Body Parameters

Example - Fetch Multiple Media (POST)

Get Preview for a Specific Media

HTTP Request

URL Parameters

Get Thumbnail for a Specific Media

HTTP Request

URL Parameters

Get Lens Preview Media

HTTP Request

URL Parameters

Example request