Skip to main content

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

AttributeDescriptionRequiredPossible Values
ad_account_idAd Account IDR
download_linkURL to Media FileREAD-ONLY
media_statusMedia StatusREAD-ONLYPENDING_UPLOAD, READY
nameMedia nameR
typeMedia TypeRVIDEO, IMAGE, LENS_PACKAGE
lens_package_metadataMetadata for lens media created by Lens StudioREAD-ONLY

Create Media

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

The above command returns JSON structured like this:

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

HTTP Request

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

Parameters

ParameterDefaultDescription
ad_account_idAd Account ID

Upload Media - Video

NameDescriptionDimensionsFile sizeFile typeLength seconds
Top SnapUsed as Top Snap video in Snap Ads, Top Snap specs1080 x 1920 px32MB max size , up to 1 GB allowed using chunked uploadmp4, movmin 3 seconds, max 180 seconds
Long form videoUsed for Long form video attachment, Long Form video attachment specsmin width 1080 px32MB max size , up to 1 GB allowed using chunked uploadmp4, movmin 15 seconds
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

The above command returns JSON structured like this:

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

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

ParameterDefaultDescription
media_idMedia ID

Upload Media - Image

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

NameDescriptionDimensionsFile sizeFile type
Top Snap ImageUsed 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 specsmin 1080 x 1920 px5 MB max sizePNG, 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 specsaspect 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 padding256 x 256 px-PNG
Preview ImageUsed as Thumbnail in Story Ad Creatives, Story Ad specsaspect ratio 3:5, min 360 x 600 px2 MB max sizePNG
Logo ImageUsed as Logo overlaid on Thumbnail in Story Ad Creatives, Story Ad specs993 x 284 px2 MB max sizePNG
Audience FilterUsed as Filter, at least 50% of the image must be transparent, Filter specs1080 x 2340 px300kb or lessPNG

Supported Optimization goals for ads using IMAGE type media are: IMPRESSIONS, SWIPES, APP_INSTALLS

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

The above command returns JSON structured like this:

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

HTTP Request

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

Parameters

ParameterDefaultDescription
media_idMedia ID

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.

  1. Split the large file
  2. Initialize a chunked upload request
  3. Get the "add_path", "finalize_path" and "upload_id" from the response, these will be unique to your upload
  4. Upload all parts of the file using the "add_path" , you will need to prepend it with https://adsapi.snapchat.com
  5. 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

ParameterDescription
actionINIT (query param)
file_nameFile Name
file_sizeTotal file size in bytes (cannot exceed 1GB)
number_of_partsNumber of parts to expect

Request and Parameters for ADD

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

ParameterDescription
fileFile Part
part_numberFile part number, used during re-assembly of file
upload_idChunked Upload ID from INIT

Request and Parameters for FINALIZE

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

ParameterDescription
upload_idChunked 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"
}

Get All Media

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"
}
}
]
}

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

ParameterDefaultDescription
ad_account_idAd Account ID

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

ParameterDescription
IDThe ID of the media to retrieve

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

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

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

AttributeDescription
icon_urlLogo used for the Lens
preview_video_urlVideo capture of the Lens
preview_image_urlImage capture of the Lens
descriptionDescription of Lens

HTTP Request

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

URL Parameters

AttributeDescription
Media IDThe 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
No

AI-Powered Search