Name: Tweet Screenshot API: Turn X Posts into PNG Images
Brand: martindata
SKU: api-martindata-tweetscreenshotgener-api
Availability: InStock
Author: API Market

# Tweet Screenshot Generator API

## Overview

The Tweet Screenshot Generator API turns public X and Twitter posts into clean images. You send post links or IDs and choose the theme, width, scale, background and padding, and the API returns a link to each image along with the post data. A single request handles up to 100 posts, and you can pick several themes to get one image per theme in the same result.

It is built for marketers, newsletter writers, video editors and social tools that need sharp post images without manual screenshots. Each result also includes the post text, author, likes, replies and media links, and you can ask for that data alone by turning off image generation.

## Features

*   **1 endpoint**: images and post data from the same call.
*   **Themes**: light, dim and dark, with several allowed in one request.
*   **Styling**: width, retina scale, background, padding, font size, border and rounded corners.
*   **Formats**: PNG with transparency, or smaller JPEG files.
*   **Post data**: text, author, likes, replies, media links and creation time.
*   **Data-only mode**: set `dataOnly` to `true` to skip the image.
*   **Result size**: up to 100 posts per request.
*   **Rate limit**: up to 10 requests per second on every plan.

## Use Cases

*   **Newsletter writers**: embed sharp post images in email.
*   **Video editors**: add readable posts to videos and slides.
*   **Social media tools**: turn saved posts into shareable cards.
*   **Research teams**: keep a visual record of public posts with their data.

## API Documentation

### Base URL

All requests go through the API.market proxy at this base URL:

```
https://prod.api.market/api/v1/martindata/tweetscreenshotgener-api
```

### Authentication

Every request must include your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Generate screenshots

Returns one result per post, with a link to each image and the post data. Requests can take up to about 60 seconds, so set your client timeout to 150 seconds.

**Method:** `POST`

**Endpoint:** `/m/tweet-screenshot-generator`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| tweets | body | Public post links (x.com, twitter.com, mobile.twitter.com, fxtwitter, vxtwitter) or bare post IDs. One image per post and theme. | array of strings | No | - | - |
| themes | body | light, dim and/or dark. Pick several to get one image per theme in the same result row (you pay per post, not per image). | array of strings | No | - | - |
| width | body | Width of the post card in CSS pixels, 320-1200. X's own embed is 550. | integer | No | - | - |
| scale | body | 1 = normal, 2 = retina (sharp on phones and slides), 3 = extra sharp. The image is width x scale pixels wide. | integer | No | - | - |
| background | body | Around the card: none (transparent PNG), white, black, gray, blue, sunset, mint, purple (gradients) or a hex colour like #ffcc00. Use it with padding. | string | No | - | - |
| padding | body | Space between the card and the image edge, 0-200. 40-60 looks good with a gradient background. | integer | No | - | - |
| format | body | png (supports transparency) or jpeg (smaller files). | string | No | - | - |
| fontSize | body | Size of the post text, 13-32. Bigger text reads better in videos and slides. | integer | No | - | - |
| showMetrics | body | Show the like and reply counts under the post. | boolean | No | - | - |
| showDate | body | Show the post time and date. | boolean | No | - | - |
| timezone | body | IANA time zone for the shown date, e.g. America/New_York or Europe/Berlin. Default UTC. | string | No | - | - |
| showMedia | body | Show attached photos (up to 4) and the video poster with a play icon. | boolean | No | - | - |
| showQuoted | body | Show a quoted post inside the card. | boolean | No | - | - |
| showReplyTo | body | For replies, show the 'Replying to @name' line. | boolean | No | - | - |
| showLogo | body | Show the X logo in the top right corner of the card. | boolean | No | - | - |
| border | body | Thin border around the card. | boolean | No | - | - |
| rounded | body | Rounded card corners (16 px). | boolean | No | - | - |
| language | body | Language code sent to the X embed endpoint (affects some labels), e.g. en, de, es. | string | No | - | - |
| dataOnly | body | Only return the post data (text, author, likes, replies, media links) without rendering images. Faster. | boolean | No | - | - |
| maxItems | body | Most posts processed in one run (and the most you pay for). | integer | No | 20 | 100 |
| includeFailed | body | Also save a row (with the error) for deleted, protected or wrong post links. These rows count as results like normal rows; when off, failures are only listed in RUN_SUMMARY. | boolean | No | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/martindata/tweetscreenshotgener-api/m/tweet-screenshot-generator' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "tweets": [
    "https://x.com/jack/status/20"
  ],
  "themes": [
    "light"
  ],
  "width": 550,
  "scale": 1,
  "format": "png",
  "maxItems": 2
}'
```

**Example Response (200 OK):**

```json
{
  "count": 1,
  "items": [
    {
      "authorAvatar": "https://pbs.twimg.com/profile_images/1661201415899951105/azNjKOSH_400x400.jpg",
      "authorHandle": "jack",
      "authorName": "jack",
      "authorVerified": true,
      "createdAt": "2006-03-21T20:50:14.000Z",
      "error": null,
      "format": "png",
      "imageHeight": 188,
      "imageWidth": 550,
      "isEdited": false,
      "isReply": false,
      "lang": "en",
      "likes": 325021,
      "media": [],
      "possiblySensitive": false,
      "quotedTweetUrl": null,
      "replies": 19255,
      "replyTo": null,
      "screenshotUrl": "https://api.apify.com/v2/key-value-stores/tTCYjme2ASBceEQxK/records/tweet-20-light.png?signature=9NegCfYbIbObAKcxwrc5",
      "screenshots": {
        "light": {
          "bytes": 17853,
          "height": 188,
          "key": "tweet-20-light.png",
          "url": "https://api.apify.com/v2/key-value-stores/tTCYjme2ASBceEQxK/records/tweet-20-light.png?signature=9NegCfYbIbObAKcxwrc5",
          "width": 550
        }
      },
      "takenAt": "2026-11-08T11:19:35Z",
      "text": "just setting up my twttr",
      "theme": "light",
      "tweetId": "20",
      "url": "https://x.com/jack/status/20"
    }
  ]
}
```

#### 2. Post data only

Set `dataOnly` to `true` to return the post data without creating an image. The parameters are the same as above.

**Method:** `POST`

**Endpoint:** `/m/tweet-screenshot-generator`

**Parameters:** None.

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/martindata/tweetscreenshotgener-api/m/tweet-screenshot-generator' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "tweets": [
    "https://x.com/XDevelopers/status/1460323737035677698"
  ],
  "dataOnly": true,
  "maxItems": 2
}'
```

**Example Response (200 OK):**

```json
{
  "count": 1,
  "items": [
    {
      "authorAvatar": "https://pbs.twimg.com/profile_images/1683501992314798080/xl1POYLw_400x400.jpg",
      "authorHandle": "XDevelopers",
      "authorName": "Developers",
      "authorVerified": true,
      "createdAt": "2021-11-15T19:08:05.000Z",
      "error": null,
      "format": "png",
      "imageHeight": null,
      "imageWidth": null,
      "isEdited": false,
      "isReply": false,
      "lang": "en",
      "likes": 901,
      "media": [
        {
          "height": 900,
          "type": "video",
          "url": "https://pbs.twimg.com/ext_tw_video_thumb/1460322142680072196/pu/img/Eg0iP3S7EWdFLjxk.jpg",
          "videoUrl": "https://video.twimg.com/ext_tw_video/1460322142680072196/pu/vid/1280x720/UySzdar5NcieJ58d.mp4?tag=12",
          "width": 1600
        }
      ],
      "possiblySensitive": false,
      "quotedTweetUrl": null,
      "replies": 138,
      "replyTo": null,
      "screenshotUrl": null,
      "screenshots": {},
      "takenAt": "2026-11-08T11:19:57Z",
      "text": "Introducing a new era for the Twitter Developer Platform! \n\n📣The Twitter API v2 is now the primary API and full of new features\n⏱Immediate access for most use cases, or apply to get more access for fr...",
      "theme": "light",
      "tweetId": "1460323737035677698",
      "url": "https://x.com/XDevelopers/status/1460323737035677698"
    }
  ]
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the response body holds the result. |
| 400 | Bad Request | A required parameter is missing or a value is invalid. Check the parameter table for the endpoint. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key is valid but your subscription does not allow this request, for example an endpoint outside your plan. |
| 404 | Not Found | The path does not exist, or the resource you asked for was not found. |
| 429 | Too Many Requests | You sent more than 10 requests per second. Slow down and retry, honouring the `Retry-After` header. |
| 500 | Internal Server Error | Something went wrong while processing the request. Retry after a short wait. |
| 503 | Service Unavailable | The service or its upstream data source is temporarily unavailable. Retry with backoff. |

## Rate Limits

Every plan allows up to 10 requests per second. Subscription plans also have a monthly call quota shown on the pricing page. Sending more than 10 requests per second returns `429 Too Many Requests`. Throttle your client to stay under 10 requests per second, back off and retry when you get a 429, and honour the `Retry-After` header when it is present.

## FAQ

*   **How is usage counted?**

    One API unit per result row. Several themes for one post are still one row.

*   **Are failed posts counted?**

    Deleted, protected or wrong post links only appear as rows when `includeFailed` is `true`, and those rows count as results.

*   **Where are the images stored?**

    `screenshotUrl` is a hosted link. If you need to keep an image, download it to your own storage.

*   **Can it capture private posts?**

    No. Only public posts work, and a missing or protected post returns the error `post not found`.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Turn public X and Twitter posts into PNG or JPEG screenshots with light, dim or dark themes, custom backgrounds and post data as JSON.

Tweet Screenshot API: Turn X Posts into PNG Images