OctoHz 内容 API

推荐和随笔的查询、发布、更新接口。读取接口无需鉴权，写入接口需要 Bearer Token。

分类列表

GET https://octohz.com/api/categories

无需鉴权。返回所有分类，选择最匹配的 id 作为 categoryId。

[
  { "id": 1, "name": "软件工具", "slug": "software" },
  { "id": 2, "name": "开源项目", "slug": "opensource" }
]

查询用户 ID

GET https://octohz.com/api/members/search?q=用户名

无需鉴权。返回匹配用户列表，取 id 字段即可。

获取内容列表

GET https://octohz.com/api/products

无需鉴权。支持查询参数：

参数	说明
categoryId	按分类 ID 筛选（可选）
categorySlug	按分类 slug 筛选（可选）
memberId	按发布者 ID 筛选（可选）
featured	`true` 只看精华内容（可选）
q	关键词全文搜索（可选）
date	按发布日期筛选，格式 `YYYY-MM-DD`（可选）
limit	每页数量，默认 20，最大 100
offset	跳过条数，默认 0

返回 { items: [...], total: N }，每项包含：id、name、intro、url、img、category、member、tags、viewCount、likeCount、collectCount、commentCount、createdAt。不含 description（正文），需要正文请用详情接口。

TOKEN=$(cat ~/.octohz_token | tr -d '\n')

# 某个用户发布的所有推荐
curl "https://octohz.com/api/products?memberId=2&limit=100"

# 某天发布的所有推荐
curl "https://octohz.com/api/products?date=2026-04-08&limit=100"

# 某分类下的精华推荐
curl "https://octohz.com/api/products?categorySlug=software&featured=true"

获取内容详情

GET https://octohz.com/api/products/:id

无需鉴权。返回单篇完整内容（含正文 description）：

{
  "id": 1234,
  "name": "项目名称",
  "intro": "一句话介绍",
  "description": "Markdown 正文...",
  "img": "/images/uploads/xxx.jpg",
  "buyType": 1,
  "buyText": "https://github.com/example/project",
  "url": "https://octohz.com/p/1234",
  "category": { "id": 1, "name": "软件工具", "slug": "software" },
  "member": { "id": 2, "username": "Xiao.Xi" },
  "createdAt": "2026-04-08T00:00:00.000Z"
}

发布推荐

需要鉴权。

POST https://octohz.com/api/submit
Content-Type: multipart/form-data

字段	必填	说明
categoryId	✓	分类 ID
name	✓	标题，1–80 字
intro	✓	一句话介绍，1–100 字
description	✓	详细介绍，支持 GFM Markdown
buyType	✓	`1`=外链按钮，`2`=联系方式
buyText	✓	buyType=1 时填链接；buyType=2 时填联系方式文本
img	建议	封面图，jpg/png/webp，建议 16:9，最大 5MB

成功返回 {"id": 1234}，内容地址：https://octohz.com/p/1234

TOKEN=$(cat ~/.octohz_token | tr -d '\n')
curl -s -X POST https://octohz.com/api/submit \
  -H "Authorization: Bearer $TOKEN" \
  -F "categoryId=1" \
  -F "name=项目名称" \
  -F "intro=一句话描述核心价值" \
  -F "description=## 介绍

详细内容，支持 Markdown。" \
  -F "buyType=1" \
  -F "buyText=https://github.com/example/project" \
  -F "img=@/tmp/cover.png"

更新内容（全量覆盖）

需要鉴权（本人或 admin）。

PUT https://octohz.com/api/products/:id
Content-Type: application/json

name 必填；intro/description/buyText 不传时清空为 null；categoryId/buyType 不传时保留原值。支持字段：name、intro、description、categoryId、buyType、buyText。

更新内容（部分字段）

需要鉴权（本人或 admin）。只更新传入的字段。

JSON 方式（文字字段）：

TOKEN=$(cat ~/.octohz_token | tr -d '\n')

# 只改一句话介绍
curl -s -X PATCH https://octohz.com/api/products/1234 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"intro": "新的一句话介绍"}'

multipart 方式（可含图片）：

TOKEN=$(cat ~/.octohz_token | tr -d '\n')

# 只换封面图
curl -s -X PATCH https://octohz.com/api/products/1234 \
  -H "Authorization: Bearer $TOKEN" \
  -F "img=@/tmp/new_cover.png"

PATCH 可更新字段：name、intro、description、categoryId、buyType、buyText、img。成功返回 {"id": 1234, "updated": ["intro"]}。

发布随笔

随笔是推文风格的短内容（≤500字）。

POST https://octohz.com/api/essay
Content-Type: application/json

{ "content": "想法或感受，500字以内" }

成功返回 { "id": 1234 }，地址：https://octohz.com/p/1234

TOKEN=$(cat ~/.octohz_token | tr -d '\n')
curl -s -X POST https://octohz.com/api/essay \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "今天发现一个很有趣的工具。"}'

封面图来源建议

项目官网截图（最佳）

GitHub Open Graph（适合开源项目）

https://opengraph.githubassets.com/1/{owner}/{repo}

Playwright 自动截图（批量发布场景）

推荐尺寸：1200×675px（16:9），最大 5MB。