Send repo name, language, and stars as JSON, get back a 1280x640 PNG ready for the Social preview field.
Open source maintainers and developer marketing teams use the GitHub social preview generator API to keep repository preview images fresh after releases, language tag changes, or org-wide rebrands. The 1280x640 output matches the field GitHub exposes under Settings > Social preview, and the layout includes the language badge, star count, and owner avatar that visitors expect to see. You post repo metadata as JSON and receive a PNG you can upload via the GitHub UI or the REST API.
curl -X POST https://app.html2img.com/api/v1/templates/github-social-preview \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"repo_name":"halberd/feather","description":"A 12kb React state management library that fits in your head.","language":"TypeScript","language_color":"#3178C6","stars":"12.4k","forks":"482","owner_name":"Halberd Software","owner_avatar_url":"https://i.pravatar.cc/160?img=8","background_color":"#0D1117","accent_color":"#58A6FF"}'
A single cURL call to render a GitHub Social Preview as a PNG. Add "format": "pdf" to the payload to get a PDF instead. For the full PHP, Node and Python equivalents, plus every input the template accepts, see the
GitHub Social Preview API reference.
Setting up your key is covered in the
authentication guide.
View the GitHub Social Preview API reference: inputs, defaults, error responses and cURL, PHP, Node and Python code samples. Read the docs.
Maintainers of small package repos refresh the social preview after every minor release. Pull the latest stars and primary language from the GitHub API, post to this endpoint, and upload the resulting PNG via the repos REST API. The preview stays current without you remembering to redesign it. Halberd Software's 14 open source packages all run this update on tag-push, and the rendered cards take about 1.2 seconds each.
Authors of npm packages or PyPI libraries benefit from a preview that shows the current version. Pass the version string to a custom field in your wrapper, render, and upload. Visitors clicking from a tweet or Slack unfurl land on a repo where the preview matches what they expected. Wren Analytics maintains 22 packages this way and reports a 16 percent uplift in clone-from-tweet rate.
Companies with 60 internal-but-public repos can apply a single visual treatment by looping the org's repo list through this endpoint. Each render uses the org logo, accent color, and font choice, while the per-repo data (name, language, description, star count) varies between requests. The result reads as one organization's output across the whole portfolio rather than 60 different design choices stitched together.
Marketing pages that highlight open source work benefit from card images that look like GitHub but live on your domain. Render once at build time, embed inline, and the page loads without an external embed call. Northwind Labs lists 8 packages on its careers page through this exact pattern, and the cards render at the same fidelity as on GitHub itself.
Speakers presenting an open source project want a high-resolution slide that reads at the back of a 200-seat room. The 1280x640 PNG scales cleanly to a 16:9 slide and shows the repo name, language, and star count without the speaker switching to the GitHub UI mid-talk. Linden & Co maintainers use this for every conference appearance.
Matches the spec at GitHub repository social preview dimensions.
These specifications describe the default PNG output. The template can also return a PDF document with selectable text through the HTML to PDF API: set format to pdf in the request. See the format parameter docs for how PDF output behaves.
POST to the template endpoint with the values you want rendered. Authenticate with your API key.
The template is rendered server-side as a 1280x640 PNG, or as a PDF document if you set format to pdf.
Cache it, embed it in your page, attach it to an email.
You upload a new preview but Twitter and Slack still show the old one for hours or days. Re-upload the file (or change the URL via the API path) to force GitHub to refresh its og:image, then refresh the link in Slack manually if needed.
Sending a generic accent color produces a badge that looks slightly off compared to the canonical color GitHub uses for that language. Pass language_color matching GitHub's linguist color list (for example, TypeScript uses #3178C6) so the card matches the actual repo page.
A 28-character org name plus a 32-character repo name overflow the header slot on a 1280-pixel canvas. Abbreviate the org or use the short org name, since the social preview is the only place the full name needs to appear.
A quick summary of what the GitHub Social Preview template accepts. The full reference, with example values and array shapes, is in the docs.
| Name | Type | Required |
|---|---|---|
repo_name | string | Required |
description | string | Optional |
language | string | Optional |
language_color | string | Optional |
stars | string | Optional |
forks | string | Optional |
owner_name | string | Optional |
owner_avatar_url | url | Optional |
background_color | string | Optional |
accent_color | string | Optional |
See the full inputs reference for descriptions, examples and validation rules.
Other templates in the content and marketing category.
Editorial hero images for blog posts and article pages
Beautiful syntax-highlighted code screenshots with window chrome
Wide email banner artwork sized for newsletter and transactional templates
Generate dynamic Open Graph images from JSON
Square cover artwork sized for Apple Podcasts, Spotify, and the major directories
Per-episode share cards sized for Twitter, LinkedIn, and Slack unfurls
E-commerce product cards with price, optional sale price, and CTA
"We shipped X" hero cards for changelogs and launch announcements
Pull-quote cards for testimonials, reviews, and shareable quotes
A starting point from each of the other two template categories.
See the full template gallery for every design grouped by category.
What dimensions does GitHub use?
GitHub recommends 1280x640 for the Social preview field under repo Settings. This template renders at exactly that size. Files larger than 1MB still upload but slow the page render, so the 80 KB to 220 KB range stays comfortable.
How do I upload it to GitHub?
Open your repo, go to Settings, scroll to "Social preview", and upload the rendered PNG. You can also do this via the REST API by PATCHing /repos/{owner}/{repo} with the og_image field set to the URL. Most CI pipelines use the API path so the upload is automated.
How do I refresh the preview after a change?
GitHub caches social images aggressively. Re-upload the file to force a fresh og:image URL. For Twitter and Slack unfurls, also clear the link cache via the platform's tools (Twitter has the Card Validator, Slack updates after a few hours).
Can I include the language and stars?
Yes, pass primary_language and star_count as inputs. The template renders the language badge in the configured color and shows the star count next to a star glyph. Both fields are optional, so you can hide them for very new repos.
Will Slack and Twitter pick this up?
Yes, both platforms read GitHub's og:image, which becomes whatever you uploaded. After upload, regenerate the cached unfurl on each platform if you need the change to appear immediately. Twitter usually picks up the change within a few minutes.
Can I generate one per release tag?
Yes, pass the version string to your render and trigger from a release-published webhook. The pipeline can render and upload in under 5 seconds, so the new preview is live before users start sharing the release on social.
25 renders a month on the free tier. See the pricing page for higher-volume plans.