API文档

ShotOG通过一次API调用生成精美OG图片。边缘原生渲染，全球极速，开发者友好，完全免费。

认证

通过 X-Api-Key 请求头或 api_key 查询参数传递API密钥。演示模式（无密钥）同样免费可用。

# 创建免费API密钥（可选）
curl -X POST https://png.qfali.cc.cd/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

# 返回: { "key": "sk_...", "tier": "free", "monthly_limit": 100000 }

生成OG图片

GET /v1/og

通过查询参数生成图片。非常适合嵌入 <meta> 标签。

# 简单调用
curl "https://png.qfali.cc.cd/v1/og?title=%E4%BD%A0%E5%A5%BD%E4%B8%96%E7%95%8C"

# 完整参数
curl "https://png.qfali.cc.cd/v1/og?title=%E6%88%91%E7%9A%84%E6%96%87%E7%AB%A0&subtitle=%E4%B8%80%E7%AF%87%E5%A5%BD%E6%96%87%E7%AB%A0&template=blog&eyebrow=%E6%8A%80%E6%9C%AF&author=%E5%BC%A0%E4%B8%89&api_key=sk_..."

POST /v1/og

通过JSON请求体生成图片。

curl -X POST https://png.qfali.cc.cd/v1/og \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_..." \
  -d '{
    "title": "我的文章",
    "template": "blog",
    "subtitle": "一篇好文章",
    "eyebrow": "技术",
    "author": "张三"
  }'

POST /v1/og/batch

单次请求最多生成20张图片。返回JSON，含base64 data URI。

curl -X POST https://png.qfali.cc.cd/v1/og/batch \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_..." \
  -d '{
    "images": [
      {"id": "hero", "title": "我的产品", "template": "product"},
      {"id": "blog-1", "title": "第一篇", "template": "blog", "author": "张三"}
    ],
    "defaults": {"format": "png", "width": 1200, "domain": "example.com"}
  }'

# 响应：
# {
#   "results": [
#     {"id":"hero","success":true,"data":"data:image/png;base64,..."},
#     {"id":"blog-1","success":true,"data":"data:image/png;base64,..."}
#   ],
#   "summary": {"total":2,"succeeded":2,"failed":0}
# }

参数说明

参数	类型	必填	说明
title	string	是	主标题文字
template	string	否	模板名（默认: basic）。可选: basic, blog, product, social, event, changelog, testimonial, announcement
subtitle	string	否	副标题或描述
eyebrow	string	否	标题上方小字（如"新品"、"博客"）
author	string	否	作者名
domain	string	否	域名水印（默认: 免费OG图生成）
bgColor	string	否	背景色（十六进制，如 #667eea）
textColor	string	否	文字色（十六进制）
accentColor	string	否	强调色（十六进制）
format	string	否	输出格式: png（默认）或 svg
width	number	否	图片宽度 200-2400（默认: 1200）
height	number	否	图片高度 200-1260（默认: 630）
fontUrl	string	否	TTF/OTF字体文件URL（最大5MB，缓存1小时）
avatar	string	否	头像图片URL（用于blog、social、testimonial模板）
logo	string	否	Logo图片URL（用于basic、product模板）

其他端点

端点	方法	说明
/v1/og/templates	GET	列出所有可用模板
/v1/keys	POST	创建新API密钥（自助服务）
/v1/keys/usage	GET	查看用量（需X-Api-Key请求头）
/v1/og/batch	POST	批量生成最多20张图片（返回JSON含base64）
/health	GET	健康检查

SDK（TypeScript / JavaScript）

npm install shotog

import { ShotOG } from "shotog";

const og = new ShotOG({ apiKey: "sk_..." });

// 生成URL（无网络请求）
const url = og.url({ title: "你好", template: "blog" });

// 生成图片二进制
const buffer = await og.generate({ title: "你好", template: "blog" });

响应头

响应头	说明
X-Cache	HIT 或 MISS — 缓存状态
X-Render-Time-Ms	总渲染耗时（毫秒）
X-SVG-Time-Ms	SVG生成耗时
X-PNG-Time-Ms	PNG转换耗时

使用限制

ShotOG 完全免费，无需注册，无月度限制。查看 价格 了解详情。