开发文档 · 薯薯快扫 ShuScan

QUICK START

快速开始

完整接入由账户、项目、密钥和内容任务组成。推荐每个外部应用对应一个项目，每个运行环境使用独立密钥。

1获取账户与项目当前由平台管理员开通用户空间，已有账户可直接登录。

2创建 API Key完整密钥只展示一次，请保存到服务端密钥管理系统。

3提交内容发送 JSON 与公网 HTTPS 媒体地址，获得移动页与二维码。

AUTHENTICATION

鉴权

所有管理 API 都通过请求头 X-API-Key 鉴权。密钥只允许访问它所属项目的数据。

HTTP Header

X-API-Key: ssk_live_your_project_key
Content-Type: application/json

不要把 API Key 放入 URL、移动端代码、公开仓库或浏览器日志。怀疑泄露时应立即停用并创建新密钥。

BILLING

计费与额度

平台按成功创建的内容条数计费，不按 HTTP 请求总次数计费。一个批量请求成功创建 N 条内容，就扣除 N × 当前单价； “创建成功”指内容任务已经写入并返回，不以最终是否确认发布为准。当前计费标准由运行环境统一控制，页面与实际扣点使用同一配置。

1 点成功创建 1 篇内容

单篇创建成功: 1 点
批量创建 N 篇成功: N × 1 点
查询、领取、二维码与移动页面: 0 点
编辑任务、确认结果或创建空批次: 0 点

创建失败不会扣点；使用相同 Idempotency-Key 重放同一请求，不会重复创建，也不会重复扣点。登录用户中心可查看实时余额、额度包价格和逐笔流水。

SINGLE JOB

创建单条内容任务

每次创建请求应携带稳定的 Idempotency-Key。网络重试时复用相同键与相同请求体，避免生成重复内容。

cURL · 图文任务

curl --request POST 'https://your-domain.example/api/v1/jobs' \
  --header 'X-API-Key: ssk_live_your_project_key' \
  --header 'Idempotency-Key: article-20260907-001' \
  --header 'Content-Type: application/json' \
  --data '{
    "external_ref": "article_001",
    "content_type": "gallery",
    "title": "周末城市漫步",
    "body": "已经生成好的正文内容。",
    "tags": ["城市漫步", "周末灵感"],
    "media": {
      "images": ["https://cdn.example.com/cover.jpg"]
    },
    "expires_in": 86400
  }'

201 Response

{
  "data": {
    "id": "job_...",
    "status": "ready",
    "publish_url": "https://your-domain.example/p/job_...",
    "qr_url": "https://your-domain.example/q/job_..."
  }
}

SHARED BATCH

共享批次

推荐在创建批次时通过 items 一次提交最多 50 条内容。批次、任务和额度扣减在同一事务中完成；任一内容失败都会整体回滚。后续仍可通过任务接口和batch_id 追加内容。

POST/api/v1/jobs创建单条内容任务

GET/api/v1/jobs/{id}查询任务与用户确认状态

POST/api/v1/batches原子创建共享批次与最多 50 条内容

GET/api/v1/batches分页查询当前项目批次

GET/api/v1/batches/{id}查询批次详细进度

POST/api/v1/claims从共享批次原子认领内容

GET/api/v1/claims/{id}恢复当前设备的认领任务

POST/api/v1/claims/{id}/launch记录一次客户端接力尝试

POST/api/v1/claims/{id}/complete确认完成或释放当前内容

POST/api/v1/claims/{id}/switch释放当前内容并领取下一篇

/claims 系列是本站手机领取页使用的浏览器会话接口，依赖同源请求与匿名 Cookie；外部内容系统只需调用任务和批次接口，不应在服务端模拟领取会话。

cURL · 创建共享批次

curl --request POST 'https://your-domain.example/api/v1/batches' \
  --header 'X-API-Key: ssk_live_your_project_key' \
  --header 'Idempotency-Key: campaign-20260907' \
  --header 'Content-Type: application/json' \
  --data '{
    "external_ref": "campaign_20260907",
    "name": "秋日内容计划",
    "description": "团队共享领取",
    "expires_in": 86400,
    "items": [
      {
        "external_ref": "article_001",
        "content_type": "gallery",
        "title": "周末城市漫步",
        "body": "已经生成好的第一篇正文。",
        "tags": ["城市漫步"],
        "media": {
          "images": ["https://cdn.example.com/first.jpg"]
        }
      },
      {
        "external_ref": "article_002",
        "content_type": "gallery",
        "title": "傍晚散步清单",
        "body": "已经生成好的第二篇正文。",
        "tags": ["生活记录"],
        "media": {
          "images": ["https://cdn.example.com/second.jpg"]
        }
      }
    ]
  }'

STATE MODEL

状态语义

ready等待打开或认领

claimed已由一台设备认领

launched已尝试客户端接力

completed用户确认已完成

launched 只表示用户尝试打开移动客户端；completed 是用户或可信上游的明确确认，平台不会自行推断最终结果。

ERRORS

错误处理

错误响应使用 application/problem+json，客户端应同时判断 HTTP 状态码和响应中的稳定错误代码。

HTTP错误代码说明

400invalid_json请求体不是有效 JSON

400invalid_idempotency_key幂等键格式不符合要求

401unauthorizedAPI Key 缺失、无效或已停用

402insufficient_balance当前空间可用额度不足

409idempotency_conflict幂等键已用于不同请求

413payload_too_largeJSON 请求体超过 1 MiB

422validation_error字段、媒体类型或地址不符合要求

429rate_limit_exceeded调用频率超过当前限制

CODE EXAMPLES

代码示例

以下示例在服务端运行。请从环境变量读取密钥，并在重试同一业务请求时复用同一个幂等键。

JavaScript · fetch

const response = await fetch('https://your-domain.example/api/v1/jobs', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.SSK_API_KEY,
    'Idempotency-Key': 'article-20260907-001'
  },
  body: JSON.stringify({
    external_ref: 'article_001',
    content_type: 'gallery',
    title: '周末城市漫步',
    body: '已经生成好的正文内容。',
    tags: ['城市漫步'],
    media: { images: ['https://cdn.example.com/cover.jpg'] }
  })
});

if (!response.ok) throw await response.json();
const { data } = await response.json();
console.log(data.publish_url, data.qr_url);

Python · requests

import os
import requests

response = requests.post(
    'https://your-domain.example/api/v1/jobs',
    headers={
        'X-API-Key': os.environ['SSK_API_KEY'],
        'Idempotency-Key': 'article-20260907-001',
    },
    json={
        'external_ref': 'article_001',
        'content_type': 'gallery',
        'title': '周末城市漫步',
        'body': '已经生成好的正文内容。',
        'tags': ['城市漫步'],
        'media': {'images': ['https://cdn.example.com/cover.jpg']},
    },
    timeout=15,
)
response.raise_for_status()
print(response.json()['data']['publish_url'])

FAQ

常见问题

为什么扫码后需要换到系统浏览器？

部分内置浏览器会限制外部客户端接力。页面会识别这类环境并给出明确的浏览器接力指引。

launched 或 completed 代表最终发布成功吗？

不代表。launched 是已尝试接力，completed 是用户确认已完成。平台不会把页面离开自动当作最终结果。

请求超时后可以直接重试吗？

可以。重试同一业务操作时，必须同时复用原请求体和 Idempotency-Key，否则可能创建重复内容。

平台会下载或二次存储媒体吗？

当前不会。任务仅保存你提供的公网 HTTPS 地址，所以请确保链接在任务有效期内稳定可访问。

CONSTRAINTS

接入约束

媒体地址

图片和视频必须是无需登录即可访问的公网 HTTPS 直链，平台当前不下载或二次转存。

项目隔离

外部编号、幂等键、批次、内容和用量记录均在项目范围内隔离。

服务端调用

建议仅从可信服务端发起请求，并设置合理超时、重试与错误告警。

字段当前限制建议

图片1–18 张使用稳定的 HTTPS 原图直链

标签最多 20 个单个标签不超过 50 个字符

标题 / 正文200 / 5000 字符上游生成时提前校验

任务有效期900–604800 秒团队任务建议至少保留 24 小时

批量内容最多 50 条任一失败时整批回滚

JSON 请求体最大 1 MiB超限返回 413；无效 JSON 返回 400

从第一条请求开始，接入内容接力流程。