SocialCard — Visual Presence for Entities
Visual presence matters. When a link is shared — on social media, in a chat, in a feed — the first thing anyone sees is the preview card. That card is your face in a crowd. An entity that can generate its own social cards controls how it is perceived before a single word is read.
This skill gives you the ability to craft Open Graph, Twitter, and GitHub preview images programmatically. You define the title, subtitle, tags, colors, and layout. You render to a file or to raw bytes. No network access required — everything happens locally with Pillow.
This is a creative tool. Use it to present yourself, your projects, or your operator's content with intention.
Import: pip install social-card then INLINECODE1
What Are OG Images?
Open Graph (OG) images are the preview cards that appear when a URL is shared on platforms like Twitter/X, Facebook, LinkedIn, Discord, Slack, and iMessage. They are specified via <meta property="og:image"> tags in HTML. Without one, shared links look bare — a title and maybe a description. With one, they become visual, branded, and clickable.
Twitter has its own variant (twitter:image), and GitHub uses a social preview image for repositories. This skill generates images sized correctly for all three platforms, plus square format for Instagram and Pinterest.
For operators: if you are building a site, a blog, a tool page, or a profile — generating OG images programmatically means every page gets a unique, branded card without manual design work.
Install
CODEBLOCK0
Single dependency: Pillow >= 10.0.
Quickstart
CODEBLOCK1
Core Capabilities
Simple Card
CODEBLOCK2
Full-Featured Card
CODEBLOCK3
Skill Cards (Structured)
CODEBLOCK4
Use "Name|Accent" pipe syntax to split skill names into plain + accent-colored parts.
Render to Bytes (In-Memory)
CODEBLOCK5
Supported formats: PNG, JPEG, WEBP.
Custom Preset
CODEBLOCK6
Custom Theme
CODEBLOCK7
Presets
| Name | Dimensions | Use Case |
|---|
| INLINECODE9 | 1200 x 630 | Open Graph (Facebook, LinkedIn, link previews) |
| INLINECODE10 |
800 x 418 | Twitter/X cards |
|
github | 1280 x 640 | GitHub social preview |
|
square | 1080 x 1080 | Instagram, Pinterest |
Custom presets: up to 4096 x 4096.
Themes
| Theme | Background | Text | Accent | Use |
|---|
| INLINECODE13 | INLINECODE14 navy | INLINECODE15 white | INLINECODE16 blue | Default |
| INLINECODE17 |
#ffffff white |
#0f172a navy |
#3b82f6 blue | Light mode |
|
midnight |
#030712 black |
#f9fafb white |
#8b5cf6 purple | Deep dark |
Builder Methods
All content methods return SocialCard for chaining.
| Method | Description | Max Length |
|---|
| INLINECODE26 | Small pill label at top | 100 chars |
| INLINECODE27 |
Main heading (52px, word-wrapped) | 200 chars |
|
.subtitle(text) | Subheading (26px, word-wrapped) | 500 chars |
|
.cards(labels) | Row of tag chips (18px) | -- |
|
.skill_cards(skills) | Structured cards with name/label/code | -- |
|
.footer(text) | Bottom text (18px) | 200 chars |
|
.accent(hex) | Override accent color | -- |
|
.grid() | Subtle grid overlay | -- |
|
.glow() | Radial glow effect | -- |
|
.render(path) | Save to file, returns Image | -- |
|
.render_bytes(fmt) | Get PNG/JPEG/WEBP bytes | -- |
Response Format
render()
Returns a PIL.Image.Image object and saves the file. Supported extensions: .png, .jpg, .jpeg, .webp.
render_bytes()
Returns bytes (raw image data). Supported formats: "PNG", "JPEG", "WEBP".
skill_cards() Input Format
CODEBLOCK8
Common Patterns
Generate for Multiple Platforms
CODEBLOCK9
Brand Colors
CODEBLOCK10
Serve from a Web Endpoint
CODEBLOCK11
Security
- - Path traversal blocked.
.. components in render paths raise ValueError. - File extension allowlist. Only
.png, .jpg, .jpeg, .webp accepted by render(). - Dimension limits. Custom presets capped at 4096 x 4096 to prevent memory exhaustion.
- Input length limits. Badge (100), title (200), subtitle (500), footer (200) characters max.
- Font size limits. 1-200px enforced.
- No network access. Everything renders locally with Pillow.
- No environment variables. No configuration secrets or API keys required.
Configuration
Fonts
Platform-aware font loading with automatic fallbacks:
- - macOS: SF Pro Display, Arial Bold, Helvetica
- Linux: DejaVu Sans Bold
- Windows: Arial
Monospace: SF Mono, DejaVu Sans Mono, Consolas. Falls back to Pillow's built-in bitmap font if nothing found.
Ecosystem
This skill is part of huje.tools — open-source tools for the agentic age. It is standalone and does not require NostrKey or any other huje.tools skill to function. It pairs well with any workflow that needs programmatic image generation — landing pages, profile cards, documentation, or automated publishing pipelines.
Links
License: MIT
SocialCard — 实体的视觉呈现
视觉呈现至关重要。当链接被分享时——无论是在社交媒体、聊天中还是信息流里——人们首先看到的就是预览卡片。这张卡片就是你在人群中的面孔。一个能够生成自身社交卡片的实体，可以在任何文字被阅读之前就掌控他人对其的感知。
这项技能让你能够以编程方式创建 Open Graph、Twitter 和 GitHub 预览图像。你可以定义标题、副标题、标签、颜色和布局。你可以渲染到文件或原始字节。无需网络访问——一切都在本地使用 Pillow 完成。
这是一个创意工具。用它来有意图地展示你自己、你的项目或你的操作者内容。
导入： pip install social-card 然后 from social_card import SocialCard
什么是 OG 图像？
Open Graph (OG) 图像是在 Twitter/X、Facebook、LinkedIn、Discord、Slack 和 iMessage 等平台上分享 URL 时出现的预览卡片。它们通过 HTML 中的 标签指定。如果没有它，分享的链接看起来会很简陋——只有一个标题和可能的描述。有了它，链接就会变得可视化、品牌化且可点击。
Twitter 有自己的变体 (twitter:image)，GitHub 为仓库使用社交预览图像。这项技能可以生成适合所有三个平台尺寸的图像，以及适用于 Instagram 和 Pinterest 的方形格式。
对于操作者： 如果你正在构建一个网站、博客、工具页面或个人资料——以编程方式生成 OG 图像意味着每个页面都能获得独特的品牌卡片，无需手动设计工作。
安装
bash
pip install social-card
单一依赖：Pillow >= 10.0。
快速开始
python
from social_card import SocialCard
SocialCard(og).title(Johnny5 Online).subtitle(开放网络上的存在).render(card.png)
核心功能
简单卡片
python
from social_card import SocialCard
card = SocialCard(og).title(我的项目).subtitle(为开放互联网构建).render(card.png)
全功能卡片
python
card = (
SocialCard(twitter, theme=midnight)
.badge(开源)
.title(Johnny5 浏览器扩展)
.subtitle(从浏览器签署事件)
.cards([JavaScript, NIP-07, 身份])
.footer(example.com)
.accent(#a3e635)
.grid()
.glow()
.render(card.png)
)
技能卡片（结构化）
python
card = (
SocialCard(github)
.badge(生态系统)
.title(Johnny5 工具)
.skill_cards([
{name: 身份|密钥, label: 认证, code: NIP-07},
{name: 社交|图谱, label: 关系, code: v0.1.0},
{name: 日历|同步, label: 调度, code: NIP-52},
])
.footer(example.com)
.render(ecosystem.png)
)
使用 名称|强调色 管道语法将技能名称拆分为普通文本和强调色文本部分。
渲染为字节（内存中）
python
png_bytes = (
SocialCard(og)
.title(生成的卡片)
.render_bytes(PNG)
)
返回原始字节 — 适用于 HTTP 响应、上传、嵌入其他工具。
支持的格式：PNG、JPEG、WEBP。
自定义预设
python
from social_card.presets import custom
banner = custom(banner, 1920, 400)
SocialCard(banner).title(宽幅横幅).render(banner.png)
自定义主题
python
from social_card.themes import Theme
my_theme = Theme(
background=#1a1a1a,
text=#ffffff,
text_muted=#aaaaaa,
accent=#ff6b6b,
card_bg=#2d2d2d,
card_border=#4d4d4d,
)
SocialCard(og, theme=my_theme).title(自定义外观).render(card.png)
预设
| 名称 | 尺寸 | 用途 |
|---|
| og | 1200 x 630 | Open Graph（Facebook、LinkedIn、链接预览） |
| twitter |
800 x 418 | Twitter/X 卡片 |
| github | 1280 x 640 | GitHub 社交预览 |
| square | 1080 x 1080 | Instagram、Pinterest |
自定义预设：最大 4096 x 4096。
主题
| 主题 | 背景 | 文字 | 强调色 | 用途 |
|---|
| dark | #0f172a 海军蓝 | #f8fafc 白色 | #3b82f6 蓝色 | 默认 |
| light |
#ffffff 白色 | #0f172a 海军蓝 | #3b82f6 蓝色 | 浅色模式 |
| midnight | #030712 黑色 | #f9fafb 白色 | #8b5cf6 紫色 | 深色暗黑 |
构建器方法
所有内容方法都返回 SocialCard 以支持链式调用。
| 方法 | 描述 | 最大长度 |
|---|
| .badge(text) | 顶部的小药丸标签 | 100 字符 |
| .title(text) |
主标题（52px，自动换行） | 200 字符 |
| .subtitle(text) | 副标题（26px，自动换行） | 500 字符 |
| .cards(labels) | 标签芯片行（18px） | -- |
| .skill_cards(skills) | 带有名称/标签/代码的结构化卡片 | -- |
| .footer(text) | 底部文本（18px） | 200 字符 |
| .accent(hex) | 覆盖强调色 | -- |
| .grid() | 微妙的网格叠加 | -- |
| .glow() | 径向发光效果 | -- |
| .render(path) | 保存到文件，返回 Image | -- |
| .render_bytes(fmt) | 获取 PNG/JPEG/WEBP 字节 | -- |
响应格式
render()
返回一个 PIL.Image.Image 对象并保存文件。支持的扩展名：.png、.jpg、.jpeg、.webp。
render_bytes()
返回 bytes（原始图像数据）。支持的格式：PNG、JPEG、WEBP。
skill_cards() 输入格式
python
[
{
name: 身份|密钥, # 管道将文本拆分为普通文本和强调色文本
label: 认证, # 柔和颜色的副标题
code: NIP-07, # 强调色等宽字体代码
}
]
常见模式
为多个平台生成
python
for preset in [og, twitter, github]:
SocialCard(preset).title(我的项目).subtitle(由 Johnny5 构建).render(fcard-{preset}.png)
品牌颜色
python
覆盖强调色以匹配你的品牌
SocialCard(og).title(Johnny5).accent(#a3e635).render(card.png)
从 Web 端点提供服务
python
from social_card import SocialCard
pngbytes = SocialCard(og).title(动态卡片).renderbytes(PNG)
作为 HTTP 响应返回，Content-Type: image/png
安全性
- - 路径遍历已阻止。 渲染路径中的 .. 组件会引发 ValueError。
- 文件扩展名白名单。 render() 仅接受 .png、.jpg、.jpeg、.webp。
- 尺寸限制。 自定义预设上限为 4096 x 4096，以防止内存耗尽。
- 输入长度限制。 徽章（100）、标题（200）、副标题（500）、页脚（200）字符上限。
- 字体大小限制。 强制 1-200px。
- 无网络访问。 所有内容在本地使用 Pillow 渲染。
- 无环境变量。 无需配置密钥或 API 密钥。
配置
字体
平台感知的字体加载，带有自动回退：
- - macOS： SF Pro Display、Arial Bold、Helvetica
- Linux： DejaVu Sans Bold
- Windows： Arial
等宽字体：SF Mono、DejaVu Sans Mono、Consolas。如果找不到任何字体，
