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 |
lens_package_metadata | Metadata for lens media created by Lens Studio | READ-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
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Upload Media - Video
Name | Description | Dimensions | File size | File type | Length seconds |
---|---|---|---|---|---|
Top Snap | Used as Top Snap video in Snap Ads, Top Snap specs | 1080 x 1920 px | 32MB max size , up to 1 GB allowed using chunked upload | mp4, mov | min 3 seconds, max 180 seconds |
Long form video | Used for Long form video attachment, Long Form video attachment specs | min width 1080 px | 32MB max size , up to 1 GB allowed using chunked upload | mp4, mov | min 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
Parameter | Default | Description |
---|---|---|
media_id | Media ID |
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 | min 1080 x 1920 px | 5 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 | 2 MB max size | 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 |
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
Parameter | Default | Description |
---|---|---|
media_id | Media 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.
- 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"
}
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
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad 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
Parameter | Description |
---|---|
ID | The 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
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"
}