link2 API

一个链接，程序化分享一切

通过 HTTP 接口创建分享页、生成 HTML 截图。所有接口走 HTTPS，使用灵途账号下颁发的 API Key 鉴权——和你在灵途其他产品里用的是同一把 Key。

接入信息

Base URL

https://link2.cn（生产环境同时支持 link2.lingtuzaowu.com）

鉴权

所有 /api/v1/* 接口均要求 Bearer Token：

Authorization: Bearer <你的灵途 API Key>

没有 Key 的话，请到 api.ailingtu.com 申请。

内容类型

所有请求体使用 application/json; charset=utf-8。

速率与限制

HTML 净化沿用站内 DOMPurify 规则，script、iframe 等会被移除。
页面单个请求体 ≤ 1MB，截图接口 HTML ≤ 5MB。
同一 Key 并发上限随灵途套餐而定。

创建分享页面

POST/api/v1/pages

用一组板块创建一个公开的 link2 短链页面。返回访问地址、编辑地址，以及一次性的编辑令牌。

请求体

{
  "title": "我的分享页",                  // 必填，1–200 字
  "description": "可选简介",              // 可选，≤500 字
  "blocks": [
    {
      "type": "richtext",
      "data": { "html": "<p>欢迎</p>" }
    },
    {
      "type": "html",
      "data": { "html": "<section>...</section>" }
    },
    {
      "type": "link_card",
      "data": {
        "items": [
          { "title": "官网", "url": "https://example.com" }
        ]
      }
    },
    {
      "type": "image",
      "data": { "url": "https://...png", "alt": "截图" }
    },
    {
      "type": "divider",
      "data": {}
    }
  ]
}

支持的板块类型

type	data 字段	说明
richtext	html (≤ 200KB)	富文本（Tiptap 渲染）
html	html (≤ 200KB)	原始 HTML，会经过净化
link_card	items[]: { title, url, description?, iconUrl? }	链接卡片聚合，1–50 项
image	url, alt?, caption?	单张图片
divider	—	分割线

cURL

curl -X POST https://link2.cn/api/v1/pages \
  -H "Authorization: Bearer $LINK2_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q3 客户交付",
    "blocks": [
      { "type": "richtext", "data": { "html": "<h2>欢迎查看</h2>" } }
    ]
  }'

响应（201）

{
  "slug": "a3kf9p",
  "title": "Q3 客户交付",
  "shareUrl": "https://link2.cn/a3kf9p",
  "editUrl": "https://link2.cn/edit/a3kf9p?token=...",
  "editToken": "一次性返回，丢了无法找回",
  "createdAt": "2026-06-11T09:30:00.000Z"
}

HTML 截图

POST/api/v1/screenshots

传入一段 HTML，服务端用无头 Chrome 渲染并返回截图链接。可选同时把这段 HTML 发布成一个 link2 短链页面。

请求体

{
  "html": "<html>...</html>",            // 必填，≤ 5MB
  "share": false,                        // 可选，默认 false
  "format": "png",                       // 可选，"png" | "jpeg"
  "fullPage": true,                      // 可选，整页截图
  "viewport": {                          // 可选
    "width": 1280,                       // 100–1920
    "height": 800                        // 100–8000
  },
  "title": "share=true 时用作页面标题",   // 可选
  "description": "share=true 时用作摘要"  // 可选
}

cURL

curl -X POST https://link2.cn/api/v1/screenshots \
  -H "Authorization: Bearer $LINK2_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<html><body><h1>Hello</h1></body></html>",
    "share": false,
    "viewport": { "width": 1280, "height": 800 }
  }'

响应（201）

share=false：

{
  "screenshot": {
    "url": "https://.../screenshots/2026-06-11/xxxxx.png",
    "contentType": "image/png",
    "size": 124356
  }
}

share=true：在上面基础上多返回 page：

{
  "screenshot": { ... },
  "page": {
    "slug": "a3kf9p",
    "title": "HTML 分享",
    "shareUrl": "https://link2.cn/a3kf9p",
    "editUrl": "https://link2.cn/edit/a3kf9p?token=...",
    "editToken": "...",
    "createdAt": "2026-06-11T09:30:00.000Z"
  }
}

截图保存在 OSS 的 screenshots/ 前缀下。MVP 阶段不做自动清理，如有保留时间需求请联系管理员配置生命周期规则。

错误响应

所有错误统一为下面的结构：

{
  "error": {
    "code": "invalid_argument",
    "message": "html 不能为空",
    "param": "html"          // 可选
  }
}

HTTP	code	含义
400	invalid_argument	参数缺失或格式错误
401	unauthorized	缺少或无效的 API Key
403	forbidden_scope	Key 没有该接口的权限
404	not_found	资源不存在
409	conflict	资源冲突（如 slug 重复）
413	payload_too_large	请求体超过限制
429	rate_limited	请求过于频繁
500	internal_error	服务端错误

需要更多能力？

批量创建、表单数据导出、自定义域名等接口正在规划。有需求请邮件联系。