Video Covers

A video's cover is the still image people see before they press play. Use setVideoCover to choose a video's cover in one of two ways:

• A frame of the video: pass offsetMs, the position of the frame in milliseconds.
• Your own image: pass imageUrl to use an image at a public URL, or imageMediaId to use an image from your Content Library.

The cover belongs to the video in your Content Library, not to a single post. Every post that uses the video gets the cover, including posts that are already scheduled, as long as the cover is set before the post publishes. This is the same cover you can pick in the Postpone web app.

Supported Platforms

Covers are ignored everywhere else, including Instagram Stories and carousels, Facebook Stories, and platforms not listed above, such as YouTube, X (Twitter), and Threads. On those, the platform picks the cover itself.

Setting a Cover

mutation setVideoCover(
  $mediaId: ID!
  $offsetMs: Int
  $imageUrl: String
  $imageMediaId: ID
) {
  setVideoCover(
    mediaId: $mediaId
    offsetMs: $offsetMs
    imageUrl: $imageUrl
    imageMediaId: $imageMediaId
  ) {
    success
    media {
      id
      name
      coverImage {
        url
        offsetMs
      }
    }
    errors {
      field
      code
      message
    }
  }
}

{
  "mediaId": "1002",
  "offsetMs": 2500
}

{
  "data": {
    "setVideoCover": {
      "success": true,
      "media": {
        "id": "1002",
        "name": "product-launch.mp4",
        "coverImage": {
          "url": "https://cdn.example.com/9c8b7a6d/",
          "offsetMs": 2500
        }
      },
      "errors": []
    }
  }
}

Pass exactly one of offsetMs, imageUrl, or imageMediaId. Setting a cover replaces the video's existing cover, if it has one.

The returned coverImage.url is always an image you can show as a preview. For offsetMs covers, it's the frame captured at that offset.

Using an Image from a URL

{
  "mediaId": "1002",
  "imageUrl": "https://example.com/images/launch-cover.jpg"
}

The image doesn't need to match the video's size, but platforms crop covers that don't match the video's aspect ratio. Use an image with the same aspect ratio as the video for the best results.

Using a Local Image

To use an image file on disk as a cover, first add it to your Content Library with a direct upload, then pass the returned media id as imageMediaId:

{
  "mediaId": "1002",
  "imageMediaId": "1003"
}

Removing a Cover

removeVideoCover removes the video's cover. Posts that use the video go back to the cover each platform picks by default. Calling it on a video without a cover is a no-op that succeeds.

mutation removeVideoCover($mediaId: ID!) {
  removeVideoCover(mediaId: $mediaId) {
    success
    media {
      id
      coverImage {
        url
      }
    }
    errors {
      field
      code
      message
    }
  }
}

{
  "mediaId": "1002"
}

{
  "data": {
    "removeVideoCover": {
      "success": true,
      "media": {
        "id": "1002",
        "coverImage": null
      },
      "errors": []
    }
  }
}

Reading a Video's Cover

The coverImage field of MediaType returns the video's current cover, or null when it has none:

query media($ids: [ID]) {
  media(ids: $ids) {
    objects {
      id
      duration
      coverImage {
        url
        offsetMs
      }
    }
  }
}

offsetMs is set for covers chosen from a frame of the video and null for covers made from your own image.

Scheduling a Reel with a Cover

Covers are set on Content Library videos, so the video has to be in your Content Library before you set its cover.

{
  "mediaId": "1002",
  "offsetMs": 2500
}

{
  "input": {
    "username": "myhandle",
    "caption": "Our new collection is here ✨",
    "media": [{ "id": "1002" }],
    "submissions": [
      {
        "postAt": "2026-12-01T15:30:00Z",
        "mediaType": "REEL"
      }
    ]
  }
}

Rate Limits

Each setVideoCover call that passes validation uploads an image, so it counts against the media upload rate limit, along with the general API rate limit. removeVideoCover only counts against the general API rate limit.

Common Errors