野生Club 的项目创建与更新全部走开放 API。你可以自己在命令行里调，也可以让 Cursor、Claude Code、Codex 等 AI 工具按文档调用。

还没有 Token？先看 提交指南 注册账号、生成 API Token。想让 AI 直接学会怎么提交，先把 AI Skill 文档 给它读。

通用约定

  • Base URL：https://yesheng.preview.tencent-zeabur.cn/api/v1

  • 鉴权：所有写接口在请求头携带你的 Token：

    Authorization: Bearer ysk_xxxxxxxxxxxxxxxx

    CLI 也可以使用等价写法：

    X-API-KEY: ysk_xxxxxxxxxxxxxxxx

  • 响应外壳：成功 { "ok": true, "data": ... }；失败 { "ok": false, "error": "CODE", "message": "..." }。

  • 公开读接口（看项目、看活动）无需鉴权。

给 AI 工具的最短上下文

如果你正在让 AI 助手接入野生Club，推荐按这个顺序给它上下文：

  1. 先读 AI Skill 文档，让它知道目标、文件结构、命令和安全规则。
  2. 再读 野生 CLI 使用指南，优先使用 ys login、ys init、ys log new、ys push。
  3. 只有 CLI 不满足时，再直接调用本页 API。

直接调 API 时，AI 必须遵守：

  • Token 只能放在请求头 Authorization: Bearer ... 或 X-API-KEY，不要写入 README、日志或提交到仓库。
  • 创建项目、更新 README、追加日志、申请 Review 都是写接口，需要用户自己的 API Token。
  • 日志是追加模型，不要覆盖旧日志；README 可以覆盖更新。
  • 图片用 multipart/form-data 上传，单张不超过 5MB。

写接口（需要 Token）

推荐新项目优先使用 ys CLI。下面的 curl 接口仍然保留，适合 AI 工具在不能使用 CLI 时直接调用。

创建项目

POST /projects

curl -X POST https://yesheng.preview.tencent-zeabur.cn/api/v1/projects \
  -H "Authorization: Bearer ysk_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "program_id": "ml2026",
    "slug": "my-cat-feeder",
    "name": "智能猫喂食器",
    "tagline": "AI 帮我记得每天按时喂猫",
    "tags": ["Hardware", "AI"]
  }'
  • program_id：你参加的活动 ID（如 ml2026 / arcade / m5stack）。
  • slug：项目唯一标识，3-32 位，只能用小写字母、数字和连字符。它会出现在项目地址里。
  • 返回：{ "ok": true, "data": { "project": { "id": "proj_xxxx", "slug": "my-cat-feeder", "url": "/projects/my-cat-feeder", ... } } }

更新项目资料

PATCH /projects/:slug — 字段全可选。

curl -X PATCH https://yesheng.preview.tencent-zeabur.cn/api/v1/projects/my-cat-feeder \
  -H "Authorization: Bearer ysk_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "tagline": "新的一句话介绍", "tags": ["AI"], "demo_urls": ["https://demo.example.com"] }'

上传 README

PUT /projects/:slug/readme —— multipart/form-data。README 是项目的公开说明，会在项目详情页渲染。

💡 智能头图提取与 Markdown 元数据 (Frontmatter)：

  1. 头图识别与提取：你无需单独上传或传递头图。后端会自动从 README 中匹配项目的头图 Banner（header_image）：

    • 精准指定：只要在 README 的某张图片 alt 属性中加入 [head] 标记（例如 ![[head] 项目主图](cover.jpg) 或 ![head](cover.jpg)，大小写均可），后端即会将其提取为头图。
    • 首图回落：若整个 README 中没有任何图片带有 [head] 标记，后端会自动把正文里的第一张图片作为头图。

  2. 标签与元数据同步：你可以在 README.md 的头部使用 YAML Frontmatter 格式标注项目元数据（如 tags 标签、tagline 一句话介绍、demo_urls 演示链接等）。后端在编译 README 时，会自动解析这些元数据并同步更新至数据库中相对应的项目属性中。

    格式示范：

    ---
tagline: AI 帮我记得每天按时喂猫
tags: [Hardware, AI]
demo_urls: [https://demo.example.com]
---

    后端不仅会提取这些属性进行项目更新，还会自动从生成的 HTML 正文中剥离这段元数据内容，保证页面排版干净不被污染。

用 < 而不是 @：readme=<README.md 让 curl 把文件文本内容作为字段发送；用 @ 会被当成附件文件。配图才用 @。

# 只传 Markdown 文本
curl -X PUT https://yesheng.preview.tencent-zeabur.cn/api/v1/projects/my-cat-feeder/readme \
  -H "Authorization: Bearer ysk_xxxx" \
  -F "readme=<README.md"

# 连相对路径引用的图片一起传（README 里写 ![](photo.jpg)）
curl -X PUT https://yesheng.preview.tencent-zeabur.cn/api/v1/projects/my-cat-feeder/readme \
  -H "Authorization: Bearer ysk_xxxx" \
  -F "readme=<README.md" \
  -F "photo.jpg=@photo.jpg"

附件只接受图片（image/*）。如果 README 里引用了图片却没一起上传，或上传了非图片文件，整个请求会返回 400 中断，不会静默吞掉。

上传项目图片资产

POST /assets/upload —— multipart/form-data。这是 CLI 使用的通用图片上传接口，会返回可写入 README、日志或 header_image 的 cloud:// file id。

curl -X POST https://yesheng.preview.tencent-zeabur.cn/api/v1/assets/upload \
  -H "X-API-KEY: ysk_xxxx" \
  -F "project_id=project_xxxx" \
  -F "file=@images/cover.png"

限制：单张图片最大 5MB；允许 png / jpg / jpeg / webp / gif；默认不接受 svg。

CLI 同步网关

POST /projects/sync —— JSON。字段名沿用现有项目模型。

{
  "project_id": "project_xxxx",
  "config": {
    "name": "猫喂食器",
    "tagline": "AI 帮我记得喂猫",
    "tags": ["Hardware"],
    "demo_urls": ["https://demo.example.com"],
    "header_image": "cloud://...",
    "visibility": "public",
    "project_status": "in_progress"
  },
  "readme_markdown": "# 猫喂食器\n...",
  "new_logs": [
    {
      "sequence": 1,
      "title": "初始化项目",
      "content_md": "今天完成了硬件选型。",
      "created_at": 1717932000
    }
  ]
}

project_status 是学生声明状态：in_progress 表示进行中，completed 表示认为当前版本已完成。严格规则：提交 completed 时必须已有 README 和至少 1 篇开发日志，否则接口返回校验错误并提示缺失项。

README 会覆盖更新；日志只追加。若某个 sequence 已存在，接口返回 409 LOG_SEQUENCE_EXISTS，不会覆盖历史日志。

提交开发日志

POST /projects/:slug/logs —— multipart/form-data。日志公开，按时间倒序显示在项目详情页，可附图。

curl -X POST https://yesheng.preview.tencent-zeabur.cn/api/v1/projects/my-cat-feeder/logs \
  -H "Authorization: Bearer ysk_xxxx" \
  -F "title=传感器终于跑起来了" \
  -F "text=困在异步死锁上两小时，用 Promise.race 加超时器解决了。" \
  -F "screenshot.jpg=@screenshot.jpg"

申请 Review

POST /projects/:slug/review/request

curl -X POST https://yesheng.preview.tencent-zeabur.cn/api/v1/projects/my-cat-feeder/review/request \
  -H "Authorization: Bearer ysk_xxxx"

前置条件：已上传 README，且至少有 1 篇日志（部分活动要求更多，见各活动手册）。AI 会基于你的 README 和全部日志出具点评与建议，并告诉管理员是否推荐展示。请求被接收后返回 202，项目状态进入 review_pending，稍后轮询状态查看进展。

查询状态

GET /projects/:slug/status — 返回项目当前状态与 Review 进展。

curl https://yesheng.preview.tencent-zeabur.cn/api/v1/projects/my-cat-feeder/status \
  -H "Authorization: Bearer ysk_xxxx"

开始 AI 面试

POST /projects/:slug/interview/start — Review 推荐后，发放一次性短效面试凭证，用于进入面试页。具体面试流程见各活动手册。

提交收件信息（领奖）

POST /projects/:slug/shipment — 项目进入 approved_to_ship（待发货）状态后，填写收件信息领取硬件奖励。

curl -X POST https://yesheng.preview.tencent-zeabur.cn/api/v1/projects/my-cat-feeder/shipment \
  -H "Authorization: Bearer ysk_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_name": "你的真名",
    "recipient_phone": "13800000000",
    "recipient_address": "详细收货地址",
    "guardian_confirmed": true
  }'

未成年人必须 guardian_confirmed: true（已获监护人知情同意）。收件信息加密存储，发货后即清除。隐私细节见各活动「领取与隐私」章节。一般情况下你也可以直接在 账号中心 用网页表单填写，不必手敲。

公开读接口（无需 Token）

接口 说明
GET /programs 全部活动列表
GET /programs/:programId 单个活动详情
GET /programs/:programId/projects 某活动下的项目
GET /docs/:programId/:docId? 文档 URL 清单；docId 省略时返回该 program 的全部 docs 链接
GET /projects?limit=40&offset=0&program_id=ml2026 项目墙；program_id 可选，省略则全站
GET /projects/:slug 单个项目详情（含 README、日志、Review 公开反馈）
GET /creators/:handle 某创作者的公开主页

项目详情数据结构

GET /api/v1/projects/:slug

{
  "ok": true,
  "data": {
    "id": "proj_xxxx",
    "slug": "my-cat-feeder",
    "name": "智能猫喂食器",
    "tagline": "AI 帮我记得每天按时喂猫",
    "tags": ["Hardware", "AI"],
    "color": "moss",
    "header_image": "cloud://yesheng-d1geg926ta28c3bc9/projects/proj_xxxx/images/photo.jpg",
    "readme_html": "<h2>智能猫喂食器</h2><p>项目说明文本...</p>",
    "shipped": true,
    "creator": {
      "display_name": "果儿",
      "handle": "guoer"
    },
    "logs": [
      {
        "id": "log_xxxx",
        "sequence": 1,
        "title": "传感器跑起来了",
        "text": "困在异步死锁上两小时，用 Promise.race 解决了。",
        "content_md": "困在异步死锁上两小时，用 Promise.race 解决了。",
        "content_html": "<p>困在异步死锁上两小时...</p>",
        "image_urls": [],
        "created_at": "2026-06-07T10:00:00Z"
      }
    ],
    "review": {
      "summary": "优秀的小助手",
      "highlights": ["接线工整", "算法逻辑严密"],
      "public_review": "非常不错的桌面造物！继续加油！"
    }
  }
}

让 AI 工具帮你调

你不必自己手敲 curl。把 AI Skill 文档、CLI 指南 和这份 API 文档交给 Cursor、Claude Code、Codex 或任何 AI 助手，让它在你的本地工作区完成提交。

推荐提示词：

请先阅读野生Club的 AI Skill 文档和 CLI 文档。
我的 API Token 是：ysk_xxxx
请用野生 CLI 初始化/更新项目，维护 README.md、images/ 和 logs/，最后运行 ys push。
不要把 Token 写入任何项目文件；不要修改已经 synced: true 的日志。