拾光集开发者 API

API 文档

通过 REST API 让你的程序或 AI 系统（如视频混剪）自动检索并使用素材。每个资源都返回 AI 可读的结构化信息：用途分类、文字描述、尺寸、主色调、时长、安装包元数据等。

概览

基础地址（Base URL）：

https://shiguang.tminos.com/api/v1

所有接口返回 JSON。除下载接口返回文件流外，其余均为标准 JSON 响应。凭据通过请求头 X-API-Key 传递。

快速开始

注册 / 登录账户。
进入控制台 → API 密钥，点击「生成密钥」。密钥只显示一次，请妥善保存。
在请求头携带密钥调用接口：

curl -H "X-API-Key: rk_你的密钥" \
  "https://shiguang.tminos.com/api/v1/resources?type=image&category=风景"

鉴权

每个请求都必须在 Header 中携带你的 API Key：

X-API-Key: rk_xxxxxxxxxxxxxxxxxxxx

密钥代表你的账户身份。使用密钥可访问所有公开资源，以及你自己上传的私有资源。请勿在前端代码或公开仓库中暴露密钥。

列出资源

GET/api/v1/resources

查询参数（均可选）：

字段	类型	说明
type	string	类型筛选：image / video / doc / installer
category	string	用途分类，如风景、人物、科技
orientation	string	图片方向：landscape / portrait / square
q	string	关键词，匹配标题与描述
sort	string	排序：new（默认）/ popular（最热）/ used（最多使用）
page	number	页码，从 1 开始，每页 24 条

示例：

curl -H "X-API-Key: rk_你的密钥" \
  "https://shiguang.tminos.com/api/v1/resources?type=video&sort=used&page=1"

响应：

{
  "page": 1,
  "hasMore": true,
  "count": 24,
  "items": [
    {
      "id": "98db8665-...",
      "title": "蓝色宽幅风景",
      "aiDescription": "纯蓝色宽屏风景，适合视频背景或转场",
      "category": "风景",
      "type": "image",
      "tags": ["蓝色", "风景", "背景"],
      "meta": {
        "mime": "image/png", "sizeBytes": 6390,
        "width": 1600, "height": 900,
        "orientation": "landscape",
        "durationSec": null, "fps": null,
        "dominantColor": "#1878c8"
      },
      "stats": { "downloads": 0, "likes": 1, "uses": 0 },
      "downloadUrl": "https://shiguang.tminos.com/api/v1/resources/98db8665-.../download",
      "useUrl": "https://shiguang.tminos.com/api/v1/resources/98db8665-.../use",
      "detailUrl": "https://shiguang.tminos.com/api/v1/resources/98db8665-..."
    }
  ]
}

资源详情

GET/api/v1/resources/:id

返回单个资源的完整 AI 卡片（字段同列表项）。

curl -H "X-API-Key: rk_你的密钥" \
  "https://shiguang.tminos.com/api/v1/resources/98db8665-..."

上传资源

POST/api/v1/resources

以 multipart/form-data 上传图片 / 视频 / 文档 / 安装包。服务端会自动提取元数据（图片主色与尺寸、视频时长与首帧封面、APK 包名等）并生成缩略图。上传为公开（public）时为你 +5 积分。

表单字段：

字段	类型	说明
file	file（必填）	要上传的文件
title	string	标题，留空用文件名
category	string	用途分类，如风景、科技
aiDescription	string	给 AI 阅读的描述，建议填写
tags	string	标签，逗号分隔
visibility	string	public（默认）/ private

示例：

curl -X POST "https://shiguang.tminos.com/api/v1/resources" \
  -H "X-API-Key: rk_你的密钥" \
  -F "file=@/path/to/photo.jpg" \
  -F "title=夕阳海岸" \
  -F "category=风景" \
  -F "aiDescription=金色夕阳下的海岸线，适合做视频背景" \
  -F "tags=风景,海洋,4K" \
  -F "visibility=public"

响应：返回该资源的完整 AI 卡片（含 id、downloadUrl 等）+ pointsAwarded。

声明使用（获得积分）

POST/api/v1/resources/:id/use

当你的程序真正使用了某素材（例如混剪进视频）时，调用此接口声明使用。同一密钥账户首次使用某资源时，会给该资源的作者 +1 积分（重复使用不会重复计分）。接口同时返回下载直链，便于一步获取素材。

curl -X POST -H "X-API-Key: rk_你的密钥" \
  "https://shiguang.tminos.com/api/v1/resources/98db8665-.../use"

响应：

{
  "ok": true,
  "resourceId": "98db8665-...",
  "firstUse": true,
  "creatorRewarded": 1,
  "downloadUrl": "https://shiguang.tminos.com/api/v1/resources/98db8665-.../download"
}

推荐流程：列出资源 → 选定素材 →声明使用 → 用返回的 downloadUrl 下载。

下载素材

GET/api/v1/resources/:id/download

返回文件二进制流（非 JSON），并带 Content-Disposition 附件头。每次调用下载计数 +1。

curl -H "X-API-Key: rk_你的密钥" \
  -o material.png \
  "https://shiguang.tminos.com/api/v1/resources/98db8665-.../download"

AI 卡片字段说明

顶层字段：

字段	类型	说明
id	string	资源唯一 ID
title	string	标题
aiDescription	string\|null	供 AI 阅读的详细描述（画面/风格/适用场景）
category	string\|null	用途分类
type	string	image / video / doc / installer / other
tags	string[]	标签
meta	object	技术元数据，见下
stats	object	downloads / likes / uses 计数
downloadUrl	string	下载直链
useUrl	string	声明使用接口

meta 字段（随类型不同而存在）：

字段	类型	说明
width / height	number	像素尺寸（图片 / 视频）
orientation	string	landscape / portrait / square
dominantColor	string	主色调十六进制，如 #1878c8（图片）
durationSec	number	时长秒数（视频）
fps	number	帧率（视频）
packageName	string	安卓包名（安装包）
versionName	string	版本号（安装包）

错误码

字段	类型	说明
200	OK	成功
401	invalid api key	缺少或无效的 X-API-Key
403	forbidden	无权访问该私有资源
404	not found	资源不存在

准备好了？

生成 API 密钥浏览资源