Twitter Screenshot API

https://twittershots.com/docs
Admin
The Twitter Screenshot API allows users to programmatically generate customizable screenshots of...
Tokens:4,907
Snippets:30
Trust Score:7.2
Update:9 months ago
Show doc for...
Tokens:
Raw
### Get API Usage (Go)

Source: https://twittershots.com/docs/api/get-usage

Implement API usage retrieval in Go using the standard net/http package. This example demonstrates making a GET request with the necessary API key header.

```go
package main

import (
	"encoding/json"
	"fmt"
	"io/ioutil"
	"log"
	"net/http"
)

func getApiUsage() {
	apiKey := "YOUR_X_API_KEY"
	url := "https://api.twittershots.com/api/v1/usage"

	client := &http.Client{}
	req, err := http.NewRequest("GET", url, nil)
	if err != nil {
		log.Fatalf("Error creating request: %v", err)
	}

	req.Header.Add("Accept", "application/json")
	req.Header.Add("X-API-KEY", apiKey)

	resp, err := client.Do(req)
	if err != nil {
		log.Fatalf("Error making request: %v", err)
	}

	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		log.Fatalf("HTTP error! status: %d", resp.StatusCode)
	}

	body, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		log.Fatalf("Error reading response body: %v", err)
	}

	var result map[string]interface{}
	if err := json.Unmarshal(body, &result); err != nil {
		log.Fatalf("Error unmarshalling JSON: %v", err)
	}

	fmt.Println("API Usage:", result)
}

func main() {
	getApiUsage()
}
```

--------------------------------

### GET /api/v1/usage

Source: https://twittershots.com/docs/api/get-usage

Retrieve your current API quota usage, including remaining requests and the total limit.

```APIDOC
## GET /api/v1/usage

### Description
Use this endpoint to retrieve your current quota usage with your API key, including `remaining` (remaining requests) and `limit` (total quota).

### Method
GET

### Endpoint
https://api.twittershots.com/api/v1/usage

### Parameters
#### Query Parameters
None

#### Headers
- **X-API-KEY** (string) - Required - Your API key.
- **Accept** (string) - Optional - `application/json`

### Request Example
```json
{
  "request": "curl --location 'https://api.twittershots.com/api/v1/usage' --header 'Accept: application/json' --header 'X-API-KEY: YOUR_X_API_KEY'"
}
```

### Response
#### Success Response (200)
- **remaining** (integer) - The number of remaining requests allowed by your quota.
- **limit** (integer) - The total number of requests allowed by your quota.

#### Response Example
```json
{
  "remaining": 1234,
  "limit": 2000
}
```

### Errors
- **401 Unauthorized**: Missing API key in header or invalid API key.
- **403 Forbidden**: No record found for the provided API key.
- **429 Too Many Requests**: The rate limit was exceeded.
- **5xx Server Error**: Indicates an error with TwitterShots servers.
```

--------------------------------

### Generate Twitter Screenshot using Python

Source: https://twittershots.com/docs/api

This Python script illustrates how to capture a Twitter screenshot using the API. It utilizes the 'requests' library to send a GET request with authentication headers and parameters for customization.

```python
import requests

def generate_twitter_screenshot(tweet_id, api_key, format='svg', theme='light', return_type='buffer'):
    """Generates a Twitter screenshot using the Twitter Screenshot API.

    Args:
        tweet_id (str): The ID of the tweet to screenshot.
        api_key (str): Your X-API-KEY for authentication.
        format (str, optional): The desired image format (svg, png, html). Defaults to 'svg'.
        theme (str, optional): The theme for the screenshot (light, dark). Defaults to 'light'.
        return_type (str, optional): The type of response (buffer, url). Defaults to 'buffer'.

    Returns:
        requests.Response or dict or None: The API response object if return_type is 'buffer',
                                           a dictionary if return_type is 'url', or None on error.
    """
    base_url = "https://api.twittershots.com/api/v1/screenshot/"
    endpoint = f"{base_url}{tweet_id}"
    headers = {
        'Accept': 'image/svg+xml,image/png,text/html',
        'X-API-KEY': api_key
    }
    params = {
        'format': format,
        'theme': theme,
        'returnType': return_type
    }

    try:
        response = requests.get(endpoint, headers=headers, params=params)
        response.raise_for_status()  # Raise an exception for bad status codes

        if return_type == 'buffer':
            return response
        elif return_type == 'url':
            return response.json()
        else:
            print(f"Unsupported returnType: {return_type}")
            return None

    except requests.exceptions.RequestException as e:
        print(f"Error generating screenshot: {e}")
        return None

# Example usage:
tweet_id = '1617979122625712128'
api_key = 'YOUR_X_API_KEY'

# Get image as buffer (default)
image_response = generate_twitter_screenshot(tweet_id, api_key, format='png', theme='dark')
if image_response:
    with open(f"screenshot_{tweet_id}.png", "wb") as f:
        f.write(image_response.content)
    print(f"Screenshot saved as screenshot_{tweet_id}.png")

# Get image URL
url_response = generate_twitter_screenshot(tweet_id, api_key, return_type='url')
if url_response:
    print(f"Image URL: {url_response['url']}")
```

--------------------------------

### Get API Usage (Python)

Source: https://twittershots.com/docs/api/get-usage

Obtain your TwitterShots API quota status with this Python script using the requests library. It sends a GET request with your API key for proper authorization.

```python
import requests

def get_api_usage():
    api_key = 'YOUR_X_API_KEY'
    url = 'https://api.twittershots.com/api/v1/usage'
    headers = {
        'Accept': 'application/json',
        'X-API-KEY': api_key
    }

    try:
        response = requests.get(url, headers=headers)
        response.raise_for_status()  # Raise an exception for bad status codes
        data = response.json()
        print('API Usage:', data)
        return data
    except requests.exceptions.RequestException as e:
        print(f'Error fetching API usage: {e}')

get_api_usage()
```

--------------------------------

### Get API Usage (JavaScript)

Source: https://twittershots.com/docs/api/get-usage

Fetch your TwitterShots API usage details using JavaScript's fetch API. Ensure your API key is correctly set in the request headers for authentication.

```javascript
async function getApiUsage() {
  const apiKey = 'YOUR_X_API_KEY';
  const url = 'https://api.twittershots.com/api/v1/usage';

  try {
    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'Accept': 'application/json',
        'X-API-KEY': apiKey
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('API Usage:', data);
    return data;
  } catch (error) {
    console.error('Error fetching API usage:', error);
  }
}

getApiUsage();
```

--------------------------------

### Get API Usage (cURL)

Source: https://twittershots.com/docs/api/get-usage

Retrieve your current API quota usage using cURL. This requires your API key in the X-API-KEY header and specifies JSON as the desired response format.

```curl
curl --location 'https://api.twittershots.com/api/v1/usage' \
--header 'Accept: application/json' \
--header 'X-API-KEY: YOUR_X_API_KEY'
```

--------------------------------

### Generate Twitter Screenshot using cURL

Source: https://twittershots.com/docs/api

This cURL command demonstrates how to generate a Twitter screenshot by making a GET request to the API endpoint. It includes essential headers for authentication and specifies desired output format and theme.

```curl
curl --location 'https://api.twittershots.com/api/v1/screenshot/1617979122625712128?format=svg&theme=light' \
--header 'Accept: image/svg+xml,image/png,text/html' \
--header 'X-API-KEY: YOUR_X_API_KEY'
```

--------------------------------

### GET /api/v1/screenshot/:statusId

Source: https://twittershots.com/docs/api

Generates a screenshot of a given tweet ID. Supports various customization options for format, theme, and display elements.

```APIDOC
## GET /api/v1/screenshot/:statusId

### Description
Generates a screenshot of a tweet using its unique status ID. This endpoint allows for extensive customization of the output image, including format, theme, aspect ratio, and the visibility of various tweet elements like text, timestamps, views, and statistics.

### Method
GET

### Endpoint
`https://api.twittershots.com/api/v1/screenshot/:statusId`

### Parameters
#### Path Parameters
- **statusId** (string) - Required - The unique identifier of the tweet to screenshot.

#### Query Parameters
- **returnType** (string) - Optional - Specifies the return type. Accepts `buffer` (default, returns image file directly) or `url` (returns a JSON object with image URL).
- **aspectRatio** (string) - Optional - Sets the aspect ratio of the screenshot. Options include `auto` (default), `1:1`, `4:5`, `5:4`, `16:9`, `9:16`.
- **format** (string) - Optional - Specifies the desired image format. Options include `svg` (default), `png`, `html`.
- **theme** (string) - Optional - Sets the visual theme of the screenshot. Options are `light` (default) and `dark`.
- **logo** (string) - Optional - Determines which logo to display. Options are `x` (default), `bluebird`, `none`.
- **showFullText** (boolean) - Optional - Controls whether the full tweet text is displayed. `true` (default) shows the full text, `false` collapses it.
- **showTimestamp** (boolean) - Optional - Controls the visibility of the tweet's timestamp. `true` (default) shows it, `false` hides it.
- **showViews** (boolean) - Optional - Controls the visibility of the tweet's view count. `true` (default) shows it, `false` hides it.
- **showStats** (boolean) - Optional - Controls the visibility of tweet statistics (replies, retweets, likes). `true` (default) shows them, `false` hides them.
- **containerBackground** (string) - Optional - Sets the background color of the screenshot container. Accepts hex colors (e.g., `#2E3748`), RGBA colors (e.g., `rgba(255, 0, 0, 0.5)`), or linear gradients.
- **backgroundImage** (string) - Optional - Provides a URL for a background image to be used in the screenshot. Must be an HTTPS URL.
- **containerPadding** (number) - Optional - Sets the padding around the tweet content in pixels. Default is `16`.
- **borderRadius** (number) - Optional - Sets the border radius for the screenshot container in pixels. Default is `16`.

### Headers
- **X-API-KEY** (string) - Required - Your API key for authentication.
- **Accept** (string) - Optional - Specifies the desired content types, e.g., `image/svg+xml, image/png, text/html`.

### Request Example
```
GET https://api.twittershots.com/api/v1/screenshot/1617979122625712128?format=svg&theme=light
Header: X-API-KEY: YOUR_X_API_KEY
Header: Accept: image/svg+xml,image/png,text/html
```

### Response
#### Success Response (200)
**If `returnType` is `buffer` (default):**
Returns the image file directly in the response body.

**If `returnType` is `url`:**
Returns a JSON object:
- **url** (string) - The URL of the generated image file.
- **format** (string) - The format of the image file (e.g., `svg`, `png`).
- **tweetId** (string) - The ID of the tweet.

#### Response Example (returnType=url)
```json
{
  "url": "https://i.twittershots.com/twitter-screenshots/2025/12/15/tweet-1998506701201473808-4a3faf1d.svg",
  "format": "svg",
  "tweetId": "1998506701201473808"
}
```
```

--------------------------------

### Generate Twitter Screenshot using JavaScript

Source: https://twittershots.com/docs/api

This JavaScript code snippet shows how to use the Twitter Screenshot API to generate a tweet screenshot. It involves making an HTTP GET request with necessary headers, including the API key and desired format.

```javascript
async function generateTwitterScreenshot(tweetId, format = 'svg', theme = 'light', apiKey) {
  const url = `https://api.twittershots.com/api/v1/screenshot/${tweetId}?format=${format}&theme=${theme}`;
  try {
    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'Accept': 'image/svg+xml,image/png,text/html',
        'X-API-KEY': apiKey
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    // Depending on returnType, you might process response as blob or json
    if (response.headers.get('content-type').includes('json')) {
        return await response.json(); // If returnType=url
    } else {
        return await response.blob(); // If returnType=buffer (default)
    }

  } catch (error) {
    console.error('Error generating screenshot:', error);
    return null;
  }
}

// Example usage:
const tweetId = '1617979122625712128';
const apiKey = 'YOUR_X_API_KEY';

generateTwitterScreenshot(tweetId, 'png', 'dark', apiKey).then(result => {
  if (result) {
    console.log('Screenshot generated:', result);
    // Handle the result (e.g., display image, save blob)
  }
});
```

--------------------------------

### Generate Twitter Screenshot using Go

Source: https://twittershots.com/docs/api

This Go program demonstrates how to fetch a Twitter screenshot via the API. It constructs the request URL, sets the necessary headers, and handles the response, allowing for different return types like image data or a URL.

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"path/filepath"
	"time"
)

func generateTwitterScreenshot(tweetID, apiKey, format, theme, returnType string) (*http.Response, error) {
	baseURL := "https://api.twittershots.com/api/v1/screenshot/"
	requestURL := fmt.Sprintf("%s%s?format=%s&theme=%s&returnType=%s", baseURL, tweetID, format, theme, returnType)

	client := &http.Client{
		Timeout: time.Second * 10,
	}

	req, err := http.NewRequest("GET", requestURL, nil)
	if err != nil {
		return nil, fmt.Errorf("failed to create request: %w", err)
	}

	req.Header.Set("Accept", "image/svg+xml,image/png,text/html")
	req.Header.Set("X-API-KEY", apiKey)

	resp, err := client.Do(req)
	if err != nil {
		return nil, fmt.Errorf("request failed: %w", err)
	}

	if resp.StatusCode != http.StatusOK {
		defer resp.Body.Close()
		return nil, fmt.Errorf("API request failed with status: %s", resp.Status)
	}

	return resp, nil
}

func main() {
	tweetID := "1617979122625712128"
	apiKey := "YOUR_X_API_KEY"
	format := "png"
	theme := "dark"
	returnType := "buffer" // or "url"

	resp, err := generateTwitterScreenshot(tweetID, apiKey, format, theme, returnType)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
		return
	}

	if resp.StatusCode == http.StatusOK {
	defer resp.Body.Close()

		if returnType == "buffer" {
			// Save the image to a file
			ext := filepath.Ext(format) // Gets the extension from format string
			filename := fmt.Sprintf("screenshot_%s.%s", tweetID, format)
			file, err := os.Create(filename)
			if err != nil {
				fmt.Fprintf(os.Stderr, "Failed to create file: %v\n", err)
				return
			}
			defer file.Close()

			_, err = io.Copy(file, resp.Body)
			if err != nil {
				fmt.Fprintf(os.Stderr, "Failed to save image: %v\n", err)
				return
			}
			fmt.Printf("Screenshot saved as %s\n", filename)
		} else if returnType == "url" {
			// Process JSON response
			var result map[string]interface{}
			decoder := json.NewDecoder(resp.Body)
			if err := decoder.Decode(&result); err != nil {
				fmt.Fprintf(os.Stderr, "Failed to decode JSON: %v\n", err)
				return
			}
			fmt.Printf("Image URL: %s\n", result["url"])
		}
	}
}
```

--------------------------------

### TwitterShots API Response Codes

Source: https://twittershots.com/docs/api

This section outlines the standard HTTP response codes returned by the TwitterShots API, categorized by success, client errors, and server errors. It also provides guidance on interpreting these codes and when to contact support.

```APIDOC
## TwitterShots API Response Codes

TwitterShots uses standard HTTP codes to indicate the success or failure of your requests. In general, 2xx HTTP codes correspond to success, 4xx codes are for user-related failures, and 5xx codes are for infrastructure issues.

If 5xx errors persist, please contact our support team at support@twittershots.com and we'll help you troubleshoot as soon as possible.

### Status Codes Overview

| Status | Description                                       |
|--------|---------------------------------------------------|
| 200    | Successful request.                               |
| 400    | Check that the parameters were correct.           |
| 401    | The API key used was missing.                     |
| 403    | The API key used was invalid.                     |
| 404    | The resource was not found.                       |
| 429    | The rate limit was exceeded.                      |
| 5xx    | Indicates an error with TwitterShots servers.     |

### Error Handling Guidance

- **2xx Codes**: Indicate that your request was processed successfully.
- **4xx Codes**: Typically indicate an issue with your request, such as incorrect parameters, missing or invalid authentication credentials, or exceeding rate limits. Review the request details and documentation for the specific error.
- **5xx Codes**: Indicate a problem on TwitterShots' servers. If these errors persist, please contact support@twittershots.com for assistance.
```
Tokens:
Raw