Home / Docs / Templates / Instagram Story template | HTML to Image API Docs

Instagram Story template

The instagram-story 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.

Marketing page

See the Instagram Story template in our gallery

Sample renders, use cases and pricing context.

View use cases →

Endpoint

POST https://app.html2img.com/api/v1/templates/instagram-story
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
`title`	string	Yes	Main headline shown in the image.	`Behind the scenes`
`subtitle`	string	No	Secondary line of text shown below the title.	`How our team built the v3 release in six weeks.`
`eyebrow`	string	No	Text value for the eyebrow.	`NEW EPISODE`
`cta`	string	No	Text value for the cta.	`Swipe up`
`background_image_url`	url	No	URL of the background image to include in the rendered image.	`https://picsum.photos/seed/insta-story/1080/1920`
`logo_url`	url	No	URL of the logo to include in the rendered image.	`-`
`background_color`	string	No	Hex colour code for the background.	`#0F0F1A`
`accent_color`	string	No	Hex colour code for the accent.	`#FACC15`

Defaults

Defaults applied automatically when not overridden in the request:

Option	Default value
`width`	`1080`
`height`	`1920`

Code examples

curl -X POST https://app.html2img.com/api/v1/templates/instagram-story \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Behind the scenes","subtitle":"How our team built the v3 release in six weeks.","eyebrow":"NEW EPISODE","cta":"Swipe up","background_image_url":"https://picsum.photos/seed/insta-story/1080/1920","background_color":"#0F0F1A","accent_color":"#FACC15"}'

<?php
$response = \Illuminate\Support\Facades\Http::withHeaders([
    'X-API-Key' => 'YOUR_API_KEY',
])->post('https://app.html2img.com/api/v1/templates/instagram-story', ['title' => 'Behind the scenes', 'subtitle' => 'How our team built the v3 release in six weeks.', 'eyebrow' => 'NEW EPISODE', 'cta' => 'Swipe up', 'background_image_url' => 'https://picsum.photos/seed/insta-story/1080/1920', 'background_color' => '#0F0F1A', 'accent_color' => '#FACC15']);

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

const response = await fetch('https://app.html2img.com/api/v1/templates/instagram-story', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "title": "Behind the scenes",
    "subtitle": "How our team built the v3 release in six weeks.",
    "eyebrow": "NEW EPISODE",
    "cta": "Swipe up",
    "background_image_url": "https://picsum.photos/seed/insta-story/1080/1920",
    "background_color": "#0F0F1A",
    "accent_color": "#FACC15"
}),
});

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

import requests

response = requests.post(
    'https://app.html2img.com/api/v1/templates/instagram-story',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={'title': 'Behind the scenes', 'subtitle': 'How our team built the v3 release in six weeks.', 'eyebrow': 'NEW EPISODE', 'cta': 'Swipe up', 'background_image_url': 'https://picsum.photos/seed/insta-story/1080/1920', 'background_color': '#0F0F1A', 'accent_color': '#FACC15'},
)

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": "instagram-story"
}

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

Other templates in the social media category:

Facebook post - Bold share images sized for Facebook feed posts
Instagram square post - Bold square images sized for the Instagram feed
LinkedIn post - Polished share images sized for LinkedIn feed posts
Pinterest pin - Vertical 2:3 pins with strong typography that stand out in feed
Tweet mockup card - Render a tweet-style card from supplied data — avatar, body, image, metrics
Twitter post - Generate share-ready images sized for Twitter/X posts
YouTube thumbnail - High-contrast 16:9 thumbnails optimized for click-through

Browse by category

A starting point from each of the other template categories. The templates index lists every reference page.

Business and commerce: Business card , Certificate of completion

Content and marketing: Blog hero image , Code screenshot

See the Instagram Story marketing page for sample renders and use cases.

Documentation