Manage media library assets

You can manage ad creatives in your business-owned media library, where they can be used and reused across multiple ad accounts. This eliminates the need to upload assets for each ad.

Media library assets are not Pins. A Pin is content published to a board for the organic Pinterest experience; a library asset is business-owned source creative reserved for advertising.

Use the media library to store and maintain business ad creatives: Rename and tag assets in bulk, list or filter what you have, remove what you no longer need.

Upload a media library asset

Step 1: Register your intent to upload media

Endpoint

POST

Example request

Set the

media_type

parameter to

media_library_image

media_library_video


curl --location --request POST 'https://api.pinterest.com/v5/media' \
  --header 'Content-Type: application/json' \
  --data-raw '{"media_type": "media_library_video"}'

Example response

The endpoint returns a

media_id

that you will pass when creating the media library asset, as well as a URL and parameters for uploading the media in the next step.


{
  "media_id": "203014033110991560",
  "media_type": "media_library_video",
  "upload_url": "https://pinterest-media-upload.s3-accelerate.amazonaws.com/",
  "upload_parameters": {
    "Content-Type": "multipart/form-data",
    "key": "uploads/11/aa/22/3:video:203014033110991560:5212123920968240771",
    "policy": "eyJleHBpcmF0aW9nIjoiMj..==",
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-credential": "ASIA6QZJ64OPIKV7FRVX/20220127/us-east-1/s3/aws4_request",
    "x-amz-date": "20220127T185143Z",
    "x-amz-security-token": "IQoJb3JpZ2luX2VjEJr...==",
    "x-amz-signature": "fcd6309a6aaee213348666a72abed8b44552a43acb6b340e8e1b288d21a5fe92"
  }
}

Step 2: Upload the media file to the Pinterest Media AWS bucket

Call the

upload_url

returned in the preceding step.

Set
Content-Type
to
multipart/form-data
.
Provide all of the
upload_parameters
returned in the preceding step as key-value pairs.
Include the media file with the format extension, such as .png, .jpg, .mp4/.mov/.m4v).

Do not provide an access token. The S3 bucket is self-signing.

Example request

Replace example values with your own IDs, tokens, and parameters before sending requests.


curl --location --request POST '{upload_url}' \
  --form 'Content-Type="{upload_parameters.Content-Type}"' \
  --form 'key="{upload_parameters.key}"' \
  --form 'policy="{upload_parameters.policy}"' \
  --form 'x-amz-algorithm="{upload_parameters.x-amz-algorithm}"' \
  --form 'x-amz-credential="{upload_parameters.x-amz-credential}"' \
  --form 'x-amz-date="{upload_parameters.x-amz-date}"' \
  --form 'x-amz-security-token="{upload_parameters.x-amz-security-token}"' \
  --form 'x-amz-signature="{upload_parameters.x-amz-signature}"' \
  --form 'file=@"{path_to_your_file}"'

A successful call returns

204 No Content

Step 3: Confirm upload

Check that your media file uploaded successfully.

Endpoint

GET

Get media upload details

Include the

media_id

from Step 1.

Example request


curl --location --request GET 'https://api.pinterest.com/v5/media/{media_id}'
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Add your token here>' \

Example response

If the request is successful, the endpoint returns metadata about the media and the

status

of the upload:

registered
: The request to register the upload was made (Step 1). Upload job was created, but the file was either not yet uploaded or accepted.
processed
: The file was uploaded to the presigned URL and/or Pinterest is still processing the upload.
succeeded
: Processing finished; the media can be used for media library asset or Pin creation.
failed
: Upload or processing failed; do not reuse this
media_id
.


{
  "media_id": "203014033110991560",
  "media_type": "media_library_video",
  "status": "registered"
}

Create the asset based on the uploaded media file

Once the file is uploaded, you can create a media library asset with it.

Endpoint

POST

Create asset(s)

Parameters

Create media library asset parameters
Parameter	Description
`business_id` String Path Required	Unique identifier for the business that owns the media file.
`media_id` String Body Required	Unique identifier for the media file, which was returned when you registered the media upload.
`name` String Body Required	Your name for the asset. For uploads, use the file name.
`tags` Array of strings Body Optional	Words to categorize the assets so that you can filter on these categories later when fetching assets. Examples: `Lifestyle` , `Product` , `Logo` , `Overlay` , and `Other` .
`ad_account_id` String Body Optional	Unique identifier for an ad account of the user that created the media file. Useful filter for asset searches.

Example request

This example shows two assets in the array.



curl --location --request POST 'https://api.pinterest.com/v5/media_library/businesses/1234567890123456789/assets' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "assets": [
      {
        "media_id": "203014033110991560",
        "name": "spring_hero.mp4",
        "tags": ["product", "video"]
      },
      {
        "media_id": "203014033110991561",
        "name": "spring_square.jpg",
        "tags": ["product", "image"]
      }
    ]
  }'

Response fields

Create media library asset response fields
Field	Description
`status` string	Overall status of the request: `SUCCESS` : Every asset in the batch succeeded. `PARTIAL_SUCCESS` : At least one asset in the batch succeeded, and at least one failed. `ERROR` : Every asset in the batch failed; none were created.
`success_count` Integer	Tally of all assets that succeeded and were created.
`failure_count` Integer	Tally of all assets that failed and were not created.
`items` array	Container for each attempted asset creation and its status.
`items.status` String	Status of the specific item in the array, either `SUCCESS` or `ERROR` .
`items.error_code` String	Reason an item failed.
`items.message` String	For a failed item, an additional explanation for the failure.
`items.asset_id` String	A unique media library identifier for an asset that succeeded. Not applied to failed assets.

Example response

Note that for multiple assets in the request, if at least one asset succeeds, the request is a success (

PARTIAL_SUCCESS


{
  "status": "PARTIAL_SUCCESS",
  "success_count": 1,
  "failure_count": 1,
  "items": [
    {
      "status": "ERROR",
      "error_code": "MEDIA_NOT_READY",
      "message": "The media for this asset is still being processed."
    },
    {
      "status": "SUCCESS",
      "message": "",
      "asset_id": "549755885176"
    }
  ]
}

Other media library asset endpoints

Was this page helpful?

{
  "media_id": "203014033110991560",
  "media_type": "media_library_video",
  "upload_url": "https://pinterest-media-upload.s3-accelerate.amazonaws.com/",
  "upload_parameters": {
    "Content-Type": "multipart/form-data",
    "key": "uploads/11/aa/22/3:video:203014033110991560:5212123920968240771",
    "policy": "eyJleHBpcmF0aW9nIjoiMj..==",
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-credential": "ASIA6QZJ64OPIKV7FRVX/20220127/us-east-1/s3/aws4_request",
    "x-amz-date": "20220127T185143Z",
    "x-amz-security-token": "IQoJb3JpZ2luX2VjEJr...==",
    "x-amz-signature": "fcd6309a6aaee213348666a72abed8b44552a43acb6b340e8e1b288d21a5fe92"
  }
}

curl --location --request POST '{upload_url}' \
  --form 'Content-Type="{upload_parameters.Content-Type}"' \
  --form 'key="{upload_parameters.key}"' \
  --form 'policy="{upload_parameters.policy}"' \
  --form 'x-amz-algorithm="{upload_parameters.x-amz-algorithm}"' \
  --form 'x-amz-credential="{upload_parameters.x-amz-credential}"' \
  --form 'x-amz-date="{upload_parameters.x-amz-date}"' \
  --form 'x-amz-security-token="{upload_parameters.x-amz-security-token}"' \
  --form 'x-amz-signature="{upload_parameters.x-amz-signature}"' \
  --form 'file=@"{path_to_your_file}"'

Create media library asset parameters

Parameter

Description

business_id

String
Path
Required

Unique identifier for the business that owns the media file.

media_id

String
Body
Required

Unique identifier for the media file, which was returned when you registered the media upload.

name

String
Body
Required

Your name for the asset. For uploads, use the file name.

tags

Array of strings
Body
Optional

Words to categorize the assets so that you can filter on these categories later when fetching assets.

Examples:

Lifestyle

Product

Logo

Overlay

, and

Other

ad_account_id

String
Body
Optional

Unique identifier for an ad account of the user that created the media file. Useful filter for asset searches.


curl --location --request POST 'https://api.pinterest.com/v5/media_library/businesses/1234567890123456789/assets' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "assets": [
      {
        "media_id": "203014033110991560",
        "name": "spring_hero.mp4",
        "tags": ["product", "video"]
      },
      {
        "media_id": "203014033110991561",
        "name": "spring_square.jpg",
        "tags": ["product", "image"]
      }
    ]
  }'

Create media library asset response fields

Field

Description

status

string

Overall status of the request:

SUCCESS
: Every asset in the batch succeeded.
PARTIAL_SUCCESS
: At least one asset in the batch succeeded, and at least one failed.
ERROR
: Every asset in the batch failed; none were created.

success_count

Integer

Tally of all assets that succeeded and were created.

failure_count

Integer

Tally of all assets that failed and were not created.

items

array

Container for each attempted asset creation and its status.

items.status

String

Status of the specific item in the array, either

SUCCESS

ERROR

items.error_code

String

Reason an item failed.

items.message

String

For a failed item, an additional explanation for the failure.

items.asset_id

String

A unique media library identifier for an asset that succeeded. Not applied to failed assets.

{
  "status": "PARTIAL_SUCCESS",
  "success_count": 1,
  "failure_count": 1,
  "items": [
    {
      "status": "ERROR",
      "error_code": "MEDIA_NOT_READY",
      "message": "The media for this asset is still being processed."
    },
    {
      "status": "SUCCESS",
      "message": "",
      "asset_id": "549755885176"
    }
  ]
}

Developer Platform

Developer Platform

Manage media library assets

Upload a media library asset

Step 1: Register your intent to upload media

Endpoint

Example request

Example response

Step 2: Upload the media file to the Pinterest Media AWS bucket

Example request

Step 3: Confirm upload

Endpoint

Example request

Example response

Create the asset based on the uploaded media file

Endpoint

Parameters

Example request

Response fields

Example response

Other media library asset endpoints

Manage media library assets

Upload a media library asset

Step 1: Register your intent to upload media

Endpoint

Example request

Example response

Step 2: Upload the media file to the Pinterest Media AWS bucket

Example request

Step 3: Confirm upload

Endpoint

Example request

Example response

Create the asset based on the uploaded media file

Endpoint

Parameters

Example request

Response fields

Example response

Other media library asset endpoints