拾光集开发者 API

API 文档

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

概览

基础地址（Base URL）：

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

所有接口返回 JSON。除下载接口返回文件流外，其余均为标准 JSON 响应。凭据推荐通过请求头 Authorization: Bearer 传递。

快速开始

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

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

鉴权

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

Authorization: Bearer rk_xxxxxxxxxxxxxxxxxxxx

兼容旧写法 X-API-Key: rk_xxx，新接入建议统一使用 Bearer。

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

访问控制

visibility 控制资源是否出现在公开列表里；downloadAccess 控制返回的文件链接如何下载。两者是独立的。

字段	类型	说明
visibility=public	可被发现	公开列表/API 列表中可见
visibility=private	不可被发现	仅上传者自己的密钥或登录态可见
downloadAccess=public	匿名下载	downloadUrl 可直接下载，适合给第三方平台抓取素材
downloadAccess=signed	限时匿名下载	downloadUrl 带 2 小时有效 token，适合临时投递
downloadAccess=api_key	密钥下载	downloadUrl 指向 /api/v1/.../download，需要 Bearer 或 X-API-Key

列出资源

GET/api/v1/resources

查询参数（均可选）：

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

示例：

curl -H "Authorization: Bearer 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 },
      "visibility": "public",
      "downloadAccess": "public",
      "downloadUrl": "https://shiguang.tminos.com/api/resources/98db8665-.../raw/photo.jpg",
      "apiDownloadUrl": "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 "Authorization: Bearer rk_你的密钥" \
  "https://shiguang.tminos.com/api/v1/resources/98db8665-..."

上传资源

POST/api/v1/resources

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

支持两种上传方式：直接传 file 文件字节，或传url/fileUrl/downloadUrl让拾光集服务端拉取远程文件。远程 URL 仅支持 http/https，并受服务端大小和超时限制。

表单字段：

字段	类型	说明
file	file	要上传的文件；与 url 二选一
url / fileUrl / downloadUrl	string	远程文件地址；与 file 二选一，服务端会下载后入库
filename / fileName	string	远程 URL 上传时可指定保存文件名，建议带扩展名
title	string	标题，留空用文件名
category	string	用途分类，如风景、科技
aiDescription	string	给 AI 阅读的描述，建议填写
tags	string	标签，逗号分隔
visibility	string	public（默认）/ private
downloadAccess	string	public（默认公开资源）/ signed / api_key

文件上传示例：

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

远程 URL 上传示例：

curl -X POST "https://shiguang.tminos.com/api/v1/resources" \
  -H "Authorization: Bearer rk_你的密钥" \
  -F "url=https://example.com/video.mp4" \
  -F "filename=video.mp4" \
  -F "title=远程视频素材" \
  -F "visibility=public" \
  -F "downloadAccess=public"

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

声明使用（获得积分）

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

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

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

响应：

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

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

下载素材

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

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

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

抖音提取音频

输入抖音分享文案或短链接，服务端会解析视频、分离音频并保存为 WAV 音频素材。默认只入库音频；如果需要同时保留原视频，可以传 saveVideo: true。

POST/api/v1/douyin/extract-audio

字段	类型	说明
text / url / shareText	string（必填）	抖音分享文案或链接，例如 https://v.douyin.com/xxxx/
saveVideo	boolean	是否同时保存原视频，默认 false

curl -X POST "https://shiguang.tminos.com/api/v1/douyin/extract-audio" \
  -H "Authorization: Bearer rk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "7.17 复制打开抖音，看看【作者的作品】https://v.douyin.com/xxxx/",
    "saveVideo": false
  }'

响应里的 resources.audio 就是已入库的 WAV 音频资源：

{
  "ok": true,
  "meta": {
    "source": "douyin",
    "shareUrl": "https://v.douyin.com/xxxx/",
    "author": "作者",
    "originalTitle": "原视频标题"
  },
  "resources": {
    "video": null,
    "audio": {
      "id": "98db8665-...",
      "title": "作者 - 原视频标题｜音频",
      "type": "audio",
      "mime": "audio/wav",
      "downloadUrl": "https://shiguang.tminos.com/api/v1/resources/98db8665-.../download",
      "apiDownloadUrl": "https://shiguang.tminos.com/api/v1/resources/98db8665-.../download",
      "detailUrl": "https://shiguang.tminos.com/api/v1/resources/98db8665-..."
    }
  }
}

生成音频

音频生成复用站内「AI 配音」能力，接口会创建后台任务。任务完成后，生成的 WAV 会自动进入你的素材库，并以audio 资源返回。

推荐流程：先获取音色 ID，或准备一个自己的 WAV 音频素材 ID；提交生成任务；轮询任务状态为done 后，使用返回的资源下载链接。

GET/api/v1/voice/profiles

列出当前密钥账户下已保存的音色。

curl -H "Authorization: Bearer rk_你的密钥" \
  "https://shiguang.tminos.com/api/v1/voice/profiles"

{
  "profiles": [
    {
      "id": "vp_或_uuid",
      "name": "我的口播音色",
      "fileName": "reference.wav",
      "mime": "audio/wav",
      "sizeBytes": 421320,
      "durationSec": 12.4,
      "createdAt": "2026-06-13T00:00:00.000Z"
    }
  ]
}

POST/api/v1/voice

请求 JSON 字段：

字段	类型	说明
text	string（必填）	要合成的口播文案，最多 2000 字
profileId	string	已保存音色 ID；与 wavResourceId / refFile 三选一
wavResourceId	string	素材库里的 WAV 音频资源 ID；与 profileId / refFile 三选一
title	string	生成后音频素材标题，留空取文案前 30 字
category	string	素材分类
visibility	string	public / private，默认 private
ttsOptions	object	高级参数：temperature、topP、topK、emotionWeight、repetitionPenalty、maxTextTokensPerSegment

curl -X POST "https://shiguang.tminos.com/api/v1/voice" \
  -H "Authorization: Bearer rk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "这里是要合成的口播文案。",
    "profileId": "音色ID",
    "title": "口播音频",
    "visibility": "private",
    "ttsOptions": {
      "temperature": 0.8,
      "topP": 0.8,
      "topK": 30,
      "emotionWeight": 0.65,
      "repetitionPenalty": 10,
      "maxTextTokensPerSegment": 120
    }
  }'

也可以直接上传参考音频：

curl -X POST "https://shiguang.tminos.com/api/v1/voice" \
  -H "Authorization: Bearer rk_你的密钥" \
  -F "text=这里是要合成的口播文案。" \
  -F "refFile=@/path/to/reference.wav" \
  -F "title=口播音频" \
  -F "visibility=private"

响应：

{
  "job": {
    "id": "vj_或_uuid",
    "text": "这里是要合成的口播文案。",
    "title": "口播音频",
    "visibility": "private",
    "status": "queued",
    "resourceId": null,
    "error": null,
    "resource": null
  }
}

GET/api/v1/voice/jobs/:id

查询任务状态。常见状态：queued、running、done、failed。

curl -H "Authorization: Bearer rk_你的密钥" \
  "https://shiguang.tminos.com/api/v1/voice/jobs/vj_或_uuid"

{
  "job": {
    "id": "vj_或_uuid",
    "status": "done",
    "resourceId": "98db8665-...",
    "error": null,
    "resource": {
      "id": "98db8665-...",
      "title": "口播音频",
      "type": "audio",
      "mime": "audio/wav",
      "fileName": "voice.wav",
      "downloadUrl": "https://shiguang.tminos.com/api/resources/98db8665-.../raw/voice.wav",
      "apiDownloadUrl": "https://shiguang.tminos.com/api/v1/resources/98db8665-.../download",
      "detailUrl": "https://shiguang.tminos.com/api/v1/resources/98db8665-..."
    }
  }
}

AI 视频

AI 视频接口复用站内「AI 视频」能力：可以直接选择已有口播音频素材，也可以用音色克隆先生成口播，再交给视频生成引擎渲染成短视频。这是后台异步任务，提交后轮询任务状态。

推荐流程：先用「生成音频」或「抖音提取音频」得到 audioResourceId，再提交 AI 视频任务。这样不会在视频任务里等待配音合成，稳定性更好。

GET/api/v1/video

列出当前密钥账户最近 50 个 AI 视频任务。

curl -H "Authorization: Bearer rk_你的密钥" \
  "https://shiguang.tminos.com/api/v1/video"

POST/api/v1/video

请求 JSON 字段：

字段	类型	说明
subject	string（必填）	视频主题
script	string（必填）	最终口播文案，最多 1200 字
audioResourceId	string	已有口播音频素材 ID；与 profileId / refFile 二选一
profileId	string	已保存音色 ID；不传 audioResourceId 时用于克隆口播
title	string	生成后视频素材标题，留空取 subject
category	string	素材分类，默认 AI视频
visibility	string	public / private，默认 public
bgmResourceId	string	当 videoOptions.bgmType=custom 时必填
videoOptions	object	视频参数：language、voiceName、platform、searchRegion、topicFocus、searchTerms、aspect、concatMode、transitionMode、clipDuration、bgmType、bgmVolume、subtitleEnabled、subtitlePosition、customPosition、fontSize、strokeWidth

curl -X POST "https://shiguang.tminos.com/api/v1/video" \
  -H "Authorization: Bearer rk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Lakers vs Celtics tonight",
    "script": "Tonight is not just another regular-season matchup. When the Lakers and Celtics meet, every possession feels like a little piece of history...",
    "audioResourceId": "音频素材ID",
    "title": "Lakers vs Celtics: why this one matters",
    "visibility": "private",
    "videoOptions": {
      "language": "en-US",
      "voiceName": "en-US-JennyNeural-Female",
      "platform": "tiktok",
      "searchRegion": "global",
      "topicFocus": "sports",
      "searchTerms": "basketball match arena fans NBA highlights",
      "aspect": "9:16",
      "concatMode": "random",
      "transitionMode": "Shuffle",
      "clipDuration": 3,
      "bgmType": "random",
      "bgmVolume": 0.14,
      "subtitleEnabled": true,
      "subtitlePosition": "custom",
      "customPosition": 74,
      "fontSize": 62,
      "strokeWidth": 3
    }
  }'

如果要直接上传参考音频生成口播，可用 multipart：

curl -X POST "https://shiguang.tminos.com/api/v1/video" \
  -H "Authorization: Bearer rk_你的密钥" \
  -F "subject=6G 从万物互联到万物智联" \
  -F "script=这里是最终口播文案。" \
  -F "refFile=@/path/to/reference.wav" \
  -F "visibility=private"

响应：

{
  "job": {
    "id": "vj_或_uuid",
    "subject": "6G 从万物互联到万物智联",
    "status": "rendering",
    "audioResourceId": "音频素材ID",
    "resourceId": null,
    "error": null,
    "resource": null
  }
}

GET/api/v1/video/jobs/:id

查询任务状态。常见状态：voice、rendering、uploading、done、failed。

curl -H "Authorization: Bearer rk_你的密钥" \
  "https://shiguang.tminos.com/api/v1/video/jobs/vj_或_uuid"

{
  "job": {
    "id": "vj_或_uuid",
    "status": "done",
    "resourceId": "98db8665-...",
    "resource": {
      "id": "98db8665-...",
      "title": "6G 到底改变什么",
      "type": "video",
      "mime": "video/mp4",
      "downloadUrl": "https://shiguang.tminos.com/api/resources/98db8665-.../raw/video.mp4",
      "apiDownloadUrl": "https://shiguang.tminos.com/api/v1/resources/98db8665-.../download",
      "detailUrl": "https://shiguang.tminos.com/api/v1/resources/98db8665-..."
    }
  }
}

真人口播视频

真人口播视频接口复用站内「真人口播」能力：选择一条已上传的人物正脸视频，再传口播文案和音色，后台会先用 IndexTTS2 生成口播 WAV，再用 MuseTalk v1.5 生成嘴型同步的成品视频。也可以直接传已有口播音频，跳过语音合成步骤，只做对口型渲染。

推荐流程：先上传拍好的视频到素材库，拿到 sourceVideoResourceId；如果已经有口播 WAV，直接传 audioResourceId，否则传音色 ID 让系统先合成口播。

GET/api/v1/lip-sync

列出当前密钥账户最近 50 个对口型任务。

curl -H "Authorization: Bearer rk_你的密钥" \
  "https://shiguang.tminos.com/api/v1/lip-sync"

POST/api/v1/lip-sync

创建真人口播视频任务。接口会立即返回 202 和任务 ID，后台异步执行；完成后用任务查询接口拿到成品视频资源 ID。

字段	类型	说明
sourceVideoResourceId	string（必填）	拍好的源视频素材 ID，必须是当前账户自己的 video 资源
text	string	要合成的口播文案，最多 1200 字；如果传 audioResourceId 可为空
voiceProfileId	string	已保存音色 ID；与 audioResourceId / refFile 三选一
audioResourceId	string	已有口播音频素材 ID；传它时不会再合成口播
title	string	成品视频标题
category	string	素材分类，默认对口型视频；真人口播场景建议传真人口播
visibility	string	public / private，默认 private
ttsOptions	object	合成口播时的 IndexTTS 参数，同生成音频接口
lipSyncOptions	object	MuseTalk v1.5 参数：bboxShift、extraMargin、parsingMode、leftCheekWidth、rightCheekWidth、batchSize

curl -X POST "https://shiguang.tminos.com/api/v1/lip-sync" \
  -H "Authorization: Bearer rk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceVideoResourceId": "拍摄视频素材ID",
    "text": "大家好，今天这条视频我们聊一个特别适合做获客的话题。",
    "voiceProfileId": "音色ID",
    "title": "婚前微电影介绍口播",
    "visibility": "private",
    "lipSyncOptions": {
      "bboxShift": 0,
      "extraMargin": 10,
      "parsingMode": "jaw",
      "batchSize": 4
    }
  }'

{
  "job": {
    "id": "任务ID",
    "status": "queued",
    "sourceVideoResourceId": "拍摄视频素材ID",
    "voiceProfileId": "音色ID",
    "audioResourceId": null,
    "resultResourceId": null,
    "meta": {
      "ttsOptions": null,
      "musetalk": {
        "bboxShift": 0,
        "extraMargin": 10,
        "parsingMode": "jaw",
        "leftCheekWidth": 90,
        "rightCheekWidth": 90,
        "batchSize": 4
      },
      "source": "api"
    }
  }
}

也可以 multipart 上传临时参考音频：

curl -X POST "https://shiguang.tminos.com/api/v1/lip-sync" \
  -H "Authorization: Bearer rk_你的密钥" \
  -F "sourceVideoResourceId=拍摄视频素材ID" \
  -F "text=这里是要说的话。" \
  -F "refFile=@/path/to/reference.wav" \
  -F "title=对口型成品"

如果已有口播音频，可以只传音频素材 ID：

curl -X POST "https://shiguang.tminos.com/api/v1/lip-sync" \
  -H "Authorization: Bearer rk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceVideoResourceId": "拍摄视频素材ID",
    "audioResourceId": "口播音频素材ID",
    "title": "已有口播音频生成真人口播",
    "category": "真人口播"
  }'

字段	类型	说明
bboxShift	number，-20 到 20，默认 0	嘴部区域上下偏移；负数通常让框更靠上，正数更靠下
extraMargin	number，0 到 40，默认 10	嘴部裁剪区域额外边距
parsingMode	string，默认 jaw	面部解析模式，默认使用下颌区域
leftCheekWidth	number，40 到 140，默认 90	左脸颊参与融合的宽度
rightCheekWidth	number，40 到 140，默认 90	右脸颊参与融合的宽度
batchSize	number，1 到 8，默认 4	MuseTalk 推理批量；显存紧张时调小

GET/api/v1/lip-sync/jobs/:id

查询任务状态。常见状态：queued、voice、rendering、uploading、done、failed。

curl -H "Authorization: Bearer rk_你的密钥" \
  "https://shiguang.tminos.com/api/v1/lip-sync/jobs/任务ID"

{
  "job": {
    "id": "任务ID",
    "status": "done",
    "sourceVideoResourceId": "拍摄视频素材ID",
    "audioResourceId": "生成或选择的口播音频ID",
    "resultResourceId": "成品视频资源ID",
    "resource": {
      "id": "成品视频资源ID",
      "type": "video",
      "mime": "video/mp4",
      "downloadUrl": "https://shiguang.tminos.com/api/v1/resources/成品视频资源ID/download"
    }
  }
}

发布抖音

发布接口复用站内「内容发布」账号。先在网页发布页添加并登录抖音账号，API 只负责把已有资源加入发布队列。抖音发布是后台异步任务，提交后用任务 ID 查询状态。

GET/api/v1/publish/accounts?platform=douyin

curl -H "Authorization: Bearer rk_你的密钥" \
  "https://shiguang.tminos.com/api/v1/publish/accounts?platform=douyin"

{
  "platform": "douyin",
  "accounts": [
    {
      "id": "acc_或_uuid",
      "platform": "douyin",
      "displayName": "抖音账号 1",
      "status": "linked",
      "createdAt": "2026-06-11T00:00:00.000Z"
    }
  ]
}

POST/api/v1/publish/douyin

请求 JSON：

字段	类型	说明
resourceId	string（必填）	要发布的视频或图片资源 ID，必须是当前密钥所属用户的资源
accountId	string	抖音账号 ID；不传则使用第一个已登录抖音账号
title	string（必填）	发布标题
description	string	发布文案，可包含 #话题
scheduledAt	string	可选 ISO 时间；不传则立即进入发布流程

curl -X POST "https://shiguang.tminos.com/api/v1/publish/douyin" \
  -H "Authorization: Bearer rk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceId": "98db8665-...",
    "accountId": "账号ID",
    "title": "今天这条内容太适合发抖音了",
    "description": "一句自然的口播说明 #热点 #AI视频"
  }'

{
  "job": {
    "id": "job_或_uuid",
    "resourceId": "98db8665-...",
    "platform": "douyin",
    "accountId": "账号ID",
    "title": "今天这条内容太适合发抖音了",
    "description": "一句自然的口播说明 #热点 #AI视频",
    "status": "publishing",
    "externalUrl": null,
    "error": null,
    "scheduledAt": null,
    "createdAt": "2026-06-11T00:00:00.000Z"
  },
  "note": "已加入发布队列，正在后台上传到抖音"
}

GET/api/v1/publish/jobs/:id

curl -H "Authorization: Bearer rk_你的密钥" \
  "https://shiguang.tminos.com/api/v1/publish/jobs/job_或_uuid"

常见状态：scheduled、publishing、published、failed、waiting_manual。

AI 卡片字段说明

顶层字段：

字段	类型	说明
id	string	资源唯一 ID
title	string	标题
aiDescription	string\|null	供 AI 阅读的详细描述（画面/风格/适用场景）
category	string\|null	用途分类
type	string	image / video / audio / doc / installer / other
visibility	string	public / private，控制是否可被发现
downloadAccess	string	public / signed / api_key，控制 downloadUrl 访问方式
tags	string[]	标签
meta	object	技术元数据，见下
stats	object	downloads / likes / uses 计数
downloadUrl	string	按 downloadAccess 生成的下载地址
apiDownloadUrl	string	始终需要 API Key 的下载接口
useUrl	string	声明使用接口

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

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

错误码

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

准备好了？

生成 API 密钥浏览资源