介绍
# OpenGraph.io
通过 OpenGraph.io API 提取网页数据、捕获截图并生成 AI 驱动的图像。
> 🤖 **AI Agents:** 如需完整的参数文档和模式，请参阅 [references/for-ai-agents.md](references/for-ai-agents.md)。
---
## 快速决策指南
### “我需要从 URL 获取数据” | 需求 | 端点 | |------|----------| | Meta 标签 / 链接预览数据 | `GET /site/{url}` | | 原始 HTML 内容 | `GET /scrape/{url}` (如果遇到地理封锁，请添加 `use_proxy=true`) | | 特定元素 (h1, h2, p) | `GET /extract/{url}?html_elements=h1,h2,p` | | 关于页面的 AI 回答 | `POST /query/{url}` ⚠️ 付费 | | 可视化截图 | `GET /screenshot/{url}` |
### “我需要生成一张图片” | 需求 | 设置 | |------|----------| | 技术图表 | `kind: "diagram"` — 使用 `diagramCode` + `diagramFormat` 进行控制 | | 应用图标/Logo | `kind: "icon"` — 设置 `transparent: true` | | 社交卡片 (OG/Twitter) | `kind: "social-card"` — 使用 `aspectRatio: "og-image"` | | 基础二维码 | `kind: "qr-code"` | | **高级二维码营销卡片** | `kind: "illustration"` — 在提示词中描述完整设计 | | 通用插图 | `kind: "illustration"` |
### 二维码：基础版 vs 高级版
**基础版** (`kind: "qr-code"`)：仅包含功能性二维码。
**高级版** (`kind: "illustration"`)：完整的营销素材，二维码嵌入在经过设计的构图中（渐变、3D 元素、号召性用语 CTA、设备模型）。示例提示词： ``` "Premium marketing card with QR code for https://myapp.com, cosmic purple gradient with floating 3D spheres, glowing accents, 'SCAN TO DOWNLOAD' call-to-action" ```
### 图表技巧 - 使用 `diagramCode` + `diagramFormat` 以获得可靠的语法（绕过 AI 生成） - 对结构关键型图表使用 `outputStyle: "standard"`（高级版可能会改变布局） - ❌ 不要混合语法与描述：`"graph LR A-->B make it pretty"` 将会失败
---
## 定价与要求
| 功能 | 免费版 | 付费计划 | |---------|-----------|------------| | Site/Unfurl | ✅ 100次/月 | 无限 | | Screenshot | ✅ 100次/月 | 无限 | | Scrape | ✅ 100次/月 | 无限 | | Extract | ✅ 100次/月 | 无限 | | Query (AI) | ❌ | ✅ | | **Image Generation** | ✅ **4次/月** | 无限 |
> 💡 **免费试用图像生成！** 免费计划每月包含 4 次高级图像生成 — 无需信用卡。
前往 [dashboard.opengraph.io](https://dashboard.opengraph.io/register) 注册。
## 快速设置
1. 在 [dashboard.opengraph.io](https://dashboard.opengraph.io/register) **注册** — 提供免费试用 2. 配置（任选其一）：
**选项 A：Clawdbot 配置**（推荐） ```json5 // ~/.clawdbot/clawdbot.json { skills: { entries: { "opengraph-io": { apiKey: "YOUR_APP_ID" } } } } ```
**选项 B：环境变量** ```bash export OPENGRAPH_APP_ID="YOUR_APP_ID" ```
---
## Clawdbot 用法 (REST API)
使用 `curl` 并结合 `OPENGRAPH_APP_ID` 环境变量。基础 URL：`https://opengraph.io/api/1.1/`
### 提取 OpenGraph 数据 (Site/Unfurl)
```bash # Get OG tags from a URL curl -s "https://opengraph.io/api/1.1/site/$(echo -n 'https://example.com' | jq -sRr @uri)?app_id=${OPENGRAPH_APP_ID}" ```
响应包含 `hybridGraph.title`、`hybridGraph.description`、`hybridGraph.image` 等。
### 网页截图
```bash # Capture screenshot (dimensions: sm, md, lg, xl) curl -s "https://opengraph.io/api/1.1/screenshot/$(echo -n 'https://example.com' | jq -sRr @uri)?app_id=${OPENGRAPH_APP_ID}&dimensions=lg" ```
响应：`{ "screenshotUrl": "https://..." }`
### 抓取 HTML 内容
```bash # Fetch rendered HTML (with optional proxy) curl -s "https://opengraph.io/api/1.1/scrape/$(echo -n 'https://example.com' | jq -sRr @uri)?app_id=${OPENGRAPH_APP_ID}&use_proxy=true" ```
### 提取特定元素
```bash # Pull h1, h2, p tags curl -s "https://opengraph.io/api/1.1/extract/$(echo -n 'https://example.com' | jq -sRr @uri)?app_id=${OPENGRAPH_APP_ID}&html_elements=h1,h2,p" ```
### Query (向 AI 询问页面内容)
```bash curl -s -X POST "https://opengraph.io/api/1.1/query/$(echo -n 'https://example.com' | jq -sRr @uri)?app_id=${OPENGRAPH_APP_ID}" \ -H "Content-Type: application/json" \ -d '{"query": "What services does this company offer?"}' ```
---
## 图像生成 (REST API)
基础 URL：`https://opengraph.io/image-agent/`
### 步骤 1：创建会话
```bash SESSION=$(curl -s -X POST "https://opengraph.io/image-agent/sessions?app_id=${OPENGRAPH_APP_ID}" \ -H "Content-Type: application/json" \ -d '{"name": "my-session"}') SESSION_ID=$(echo $SESSION | jq -r '.sessionId') ```
### 步骤 2：生成图像
```bash curl -s -X POST "https://opengraph.io/image-agent/sessions/${SESSION_ID}/generate?app_id=${OPENGRAPH_APP_ID}" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A beautiful QR code linking to https://example.com with modern gradient design", "kind": "qr-code", "aspectRatio": "square", "quality": "high" }' ```
**图像类型 (kinds)：** `illustration`、`diagram`、`icon`、`social-card`、`qr-code`
**风格预设：** `github-dark`、`vercel`、`stripe`、`neon-cyber`、`pastel`、`minimal-mono`
**长宽比：** `square`、`og-image` (1200×630)、`twitter-card`、`instagram-story` 等。
### 步骤 3：下载资源
```bash ASSET_ID="<from-generate-response>" curl -s "https://opengraph.io/image-agent/assets/${ASSET_ID}/file?app_id=${OPENGRAPH_APP_ID}" -o output.png ```
### 步骤 4：迭代 (优化图像)
```bash curl -s -X POST "https://opengraph.io/image-agent/sessions/${SESSION_ID}/iterate?app_id=${OPENGRAPH_APP_ID}" \ -H "Content-Type: application/json" \ -d '{ "assetId": "<previous-asset-id>", "prompt": "Change the background to blue" }' ```
---
## 自然语言示例
当用户使用自然语言提问时，将其转换为相应的 API 调用：
| 用户提问 | 使用的 API | |-----------|------------| | "从 URL 获取 OG 标签" | `GET /site/{url}` | | "截图这个页面" | `GET /screenshot/{url}` | | "从 URL 抓取 HTML" | `GET /scrape/{url}` | | "这个页面关于 X 说了什么？" | `POST /query/{url}` | | "为 URL 生成一个二维码" | `POST /image-agent/sessions/{id}/generate` 并带上 `kind: "qr-code"` | | "创建一个高级二维码营销卡片" | `POST /image-agent/sessions/{id}/generate` 并带上 `kind: "illustration"` + 在提示词中描述设计 | | "为我的博客创建一张社交卡片" | `POST /image-agent/sessions/{id}/generate` 并带上 `kind: "social-card"` | | "制作一张架构图" | `POST /image-agent/sessions/{id}/generate` 并带上 `kind: "diagram"` |
### 二维码选项
**基础二维码** (`kind: "qr-code"`)：仅生成具有极简样式的功能性二维码。
**高级二维码营销卡片** (`kind: "illustration"`)：生成完整的营销素材，二维码嵌入在专业设计的构图中——包括渐变、3D 元素、号召性用语 (CTA)、设备模型等。
```bash # Premium QR marketing card example curl -s -X POST "https://opengraph.io/image-agent/sessions/${SESSION_ID}/generate?app_id=${OPENGRAPH_APP_ID}" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Premium marketing card with QR code for https://myapp.com, cosmic purple gradient background with floating 3D spheres, glowing accents, SCAN TO DOWNLOAD call-to-action", "kind": "illustration", "aspectRatio": "square", "outputStyle": "premium", "brandColors": ["#6B4CE6", "#9B6DFF"], "stylePreferences": "modern, cosmic, premium marketing, 3D elements" }' ```
---
## MCP 集成 (适用于 Claude Desktop、Cursor 等)
对于支持 MCP 的 AI 客户端，请使用 MCP 服务器：
```bash # Interactive installer npx opengraph-io-mcp --client cursor --app-id YOUR_APP_ID
# Or configure manually: { "mcpServers": { "opengraph": { "command": "npx", "args": ["-y", "opengraph-io-mcp"], "env": { "OPENGRAPH_APP_ID": "YOUR_APP_ID" } } } } ```
针对特定客户端的设置，请参阅 [references/mcp-clients.md](references/mcp-clients.md)。
## 更多详情
- [references/for-ai-agents.md](references/for-ai-agents.md) — **AI agent 参考**（工具架构、决策树、模式） - [references/api-reference.md](references/api-reference.md) — **完整 API 文档**（所有端点、参数、响应架构） - [references/platform-support.md](references/platform-support.md) — **平台支持指南**（YouTube、Vimeo、TikTok、社交媒体、电子商务） - [references/troubleshooting.md](references/troubleshooting.md) — **故障排除指南**（常见错误、调试技巧） - [references/image-generation.md](references/image-generation.md) — 图像预设、风格、模板 - [references/mcp-clients.md](references/mcp-clients.md) — MCP 客户端配置