Docs / Templates / Tweet Mockup Card template

Tweet Mockup Card template

The tweet-mockup-card template renders a social image as a PNG. POST a JSON payload to the endpoint below and you receive a CDN URL in the response.

Endpoint

POST https://html2img.com/api/v1/templates/tweet-mockup-card
X-API-Key: <your-api-key>
Content-Type: application/json

Authentication uses the X-API-Key header. See the authentication docs for details on issuing and rotating keys.

Inputs

The full set of inputs the template accepts:

Name	Type	Required	Description	Example
`display_name`	string	Yes	Text value for the display name.	`Jordan Whitfield`
`handle`	string	Yes	Text value for the handle.	`@jwhitfield`
`body`	string	Yes	Text value for the body.	`shipped a tiny side project this weekend and it already has more users than my last YC company funny how that works`
`avatar_url`	url	No	URL of the avatar to include in the rendered image.	`https://i.pravatar.cc/160?img=15`
`verified`	enum (none \| blue \| gold)	No	One of the supported verified values listed below.	`blue`
`image_url`	url	No	URL of the image to include in the rendered image.	`—`
`timestamp`	string	No	Text value for the timestamp.	`8:14 AM · Apr 30, 2026`
`replies`	string	No	Text value for the replies.	`124`
`retweets`	string	No	Text value for the retweets.	`512`
`likes`	string	No	Text value for the likes.	`4.2K`
`views`	string	No	Text value for the views.	`182K`
`theme`	enum (light \| dim \| dark)	No	One of the supported theme values listed below.	`light`

Enum values

verified accepts one of: none , blue , gold .

theme accepts one of: light , dim , dark .

Defaults

Defaults applied automatically when not overridden in the request:

Option	Default value
`width`	`1200`
`height`	`800`

Code examples

curl -X POST https://app.html2img.com/api/v1/templates/tweet-mockup-card \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"Jordan Whitfield","handle":"@jwhitfield","body":"shipped a tiny side project this weekend and it already has more users than my last YC company\n\nfunny how that works","avatar_url":"https://i.pravatar.cc/160?img=15","verified":"blue","timestamp":"8:14 AM \u00b7 Apr 30, 2026","replies":"124","retweets":"512","likes":"4.2K","views":"182K","theme":"light"}'

<?php
$response = \Illuminate\Support\Facades\Http::withHeaders([
    'X-API-Key' => 'YOUR_API_KEY',
])->post('https://app.html2img.com/api/v1/templates/tweet-mockup-card', ['display_name' => 'Jordan Whitfield', 'handle' => '@jwhitfield', 'body' => 'shipped a tiny side project this weekend and it already has more users than my last YC company

funny how that works', 'avatar_url' => 'https://i.pravatar.cc/160?img=15', 'verified' => 'blue', 'timestamp' => '8:14 AM · Apr 30, 2026', 'replies' => '124', 'retweets' => '512', 'likes' => '4.2K', 'views' => '182K', 'theme' => 'light']);

$url = $response->json('url');

const response = await fetch('https://app.html2img.com/api/v1/templates/tweet-mockup-card', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "display_name": "Jordan Whitfield",
    "handle": "@jwhitfield",
    "body": "shipped a tiny side project this weekend and it already has more users than my last YC company\n\nfunny how that works",
    "avatar_url": "https://i.pravatar.cc/160?img=15",
    "verified": "blue",
    "timestamp": "8:14 AM \u00b7 Apr 30, 2026",
    "replies": "124",
    "retweets": "512",
    "likes": "4.2K",
    "views": "182K",
    "theme": "light"
}),
});

const { url } = await response.json();

import requests

response = requests.post(
    'https://app.html2img.com/api/v1/templates/tweet-mockup-card',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={'display_name': 'Jordan Whitfield', 'handle': '@jwhitfield', 'body': 'shipped a tiny side project this weekend and it already has more users than my last YC company

funny how that works', 'avatar_url': 'https://i.pravatar.cc/160?img=15', 'verified': 'blue', 'timestamp': '8:14 AM · Apr 30, 2026', 'replies': '124', 'retweets': '512', 'likes': '4.2K', 'views': '182K', 'theme': 'light'},
)

url = response.json()['url']

Looking for a fuller integration sketch in your language? The usage guides cover PHP, Laravel, Rails, Python, JavaScript, React and Vue.

Response

A successful render returns:

{
  "success": true,
  "id": "abc123",
  "url": "https://i.html2img.com/abc123.png",
  "credits_remaining": 1234,
  "template": "tweet-mockup-card"
}

The url field is a CDN URL for the rendered PNG. credits_remaining tracks your monthly quota. Shared response fields are documented in the API parameters reference.

Errors

The template endpoint returns the following error responses:

422 Validation failed

Returned when one or more inputs fail validation. The errors object lists field-specific messages.

{
  "success": false,
  "error": "validation_failed",
  "errors": {
    "title": ["The title field is required."]
  }
}

404 Template not found

Returned with {"code": "template_not_found"} if the slug is not registered. Check the template list for current slugs.

401 Unauthorised

Missing or invalid API key. See the authentication docs.

429 Too many requests

You have hit the rate limit or used your monthly credits. The pricing page covers higher-volume plans.

Related templates

Instagram Square Post — Bold square images sized for the Instagram feed
Open Graph Image — Generate dynamic Open Graph images from JSON
Twitter/X Post Image — Generate share-ready images sized for Twitter/X posts
YouTube Thumbnail — High-contrast 16:9 thumbnails optimized for click-through

See the Tweet Mockup Card template in our gallery for sample renders and use cases.

Documentation