---
title: "GitHub Social Preview Generator: Repo Card PNGs"
description: "Render repo cards with the GitHub social preview generator API. POST repo metadata, stars, and language as JSON, get a 1280x640 PNG ready to upload."
url: "https://html2img.com/templates/github-social-preview/"
---

# Github Social Preview Generator API

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.

## At a glance

- **Template slug:** `github-social-preview`
- **Category:** developer
- **Endpoint:** `POST https://app.html2img.com/api/v1/templates/github-social-preview`
- **Authentication:** `X-API-Key` header
- **Cost:** one credit per render, PNG or PDF
- **Page:** https://html2img.com/templates/github-social-preview/

## Fields

| Field | Type | Required | Example |
| --- | --- | --- | --- |
| `repo_name` | string | Yes | halberd/feather |
| `description` | string | No | A 12kb React state management library that fits in your head. |
| `language` | string | No | TypeScript |
| `language_color` | string | No | #3178C6 |
| `stars` | string | No | 12.4k |
| `forks` | string | No | 482 |
| `owner_name` | string | No | Halberd Software |
| `owner_avatar_url` | url | No | https://i.pravatar.cc/160?img=8 |
| `background_color` | string | No | #0D1117 |
| `accent_color` | string | No | #58A6FF |

## Defaults

| Field | Default |
| --- | --- |
| `width` | 1280 |
| `height` | 640 |

## Example request

```bash
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"}'
```

## In your language

### PHP

```php
<?php
$response = \Illuminate\Support\Facades\Http::withHeaders([
    'X-API-Key' => 'YOUR_API_KEY',
])->post('https://app.html2img.com/api/v1/templates/github-social-preview', ['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']);

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

### Node.js

```javascript
const response = await fetch('https://app.html2img.com/api/v1/templates/github-social-preview', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "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"
}),
});

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

### Python

```python
import requests

response = requests.post(
    'https://app.html2img.com/api/v1/templates/github-social-preview',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={'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'},
)

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

## What it is for

### Maintainers auto-generating previews from repo metadata

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.

### Package authors keeping previews fresh after releases

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.

### Organizations standardizing previews across repos

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.

### Developer marketing pages embedding repo cards

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.

### Conference talk slides showing GitHub repos

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.

## Output

- **Dimensions:** 1280x640
- **Colour space:** sRGB
- **Transparency:** Not supported
- **Typical file size:** 80 KB to 220 KB
- **Platform specification:** [GitHub repository social preview dimensions](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/customizing-your-repositorys-social-media-preview)

## Common mistakes

### GitHub does not regenerate cached previews automatically

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.

### Language tag color mismatches GitHub badge color

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.

### Owner name truncation when org and repo names are both long

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.

## Questions

### 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.

## Preview

![Github Social Preview Generator API example render](https://i.html2img.com/image-1777560086330-30270.png)

## Related templates

- [project-showcase](https://html2img.com/templates/project-showcase/)
- [code-screenshot](https://html2img.com/templates/code-screenshot/)

## See also

- [Every template](https://html2img.com/templates/)
- [Templates API reference](https://html2img.com/docs/templates/)
- [OpenAPI specification](https://html2img.com/openapi.json)