开发者接入

小红书交稿 API 文档

三个步骤：准备图片、创建交稿包、把返回的链接交给发布人。成功响应的 code 为 0；失败响应的 code 为 -1。请同时判断 HTTP 状态和业务码。

export NOTEHANDOFF_KEY="sk_REPLACE_WITH_YOUR_KEY"
export BASE="https://tudilink.com"

# 可选：逐张上传自己的图片，保存返回的 data.url
curl -sS -X POST "$BASE/api/assets" \
  -H "Authorization: Bearer $NOTEHANDOFF_KEY" \
  -F "file=@./cover.jpg"

# 创建交稿包；重试时保留相同业务稿件版本与幂等键
curl -sS -X POST "$BASE/api/v1/handoffs" \
  -H "Authorization: Bearer $NOTEHANDOFF_KEY" \
  -H "Idempotency-Key: article-001:v1" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "一份图文，交到手机",
  "content": "这是用于体验交稿流程的测试图文。请核对图片顺序与正文，再决定是否发布。",
  "images": [
    "https://tudilink.com/demo/01.png",
    "https://tudilink.com/demo/02.png"
  ]
}'

# 把创建响应的 data.url 发给发布人

认证

服务端调用在请求头携带 API Key。完整 Key 只在创建时显示一次；服务端保存摘要。密钥丢失后应创建新 Key 并撤销旧 Key。

上传素材

POST /api/assets

使用 multipart/form-data，只有一个 file 字段，一次上传一张。服务按文件签名检查 PNG、JPEG、静态 WebP，单张不超过 10 MiB，并返回宽高和素材到期时间。

某张失败时保留已成功的图片，只重传失败项。创建稿件时以 images 数组决定准备和传递顺序；进入 App 后仍需核对。

素材地址 /m/:key 可公开读取，从上传时起 7 天有效。长图保留原尺寸，文件头检查不代表所有 App 都能完整解码。

创建交稿包

POST /api/v1/handoffs

创建响应示例

新建为 HTTP 201；同键同内容重放为 HTTP 200。示例省略部分稿件字段；实际 id 为 UUID，token 为 43 位 base64url，值以响应为准。

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "token": "<HANDOFF_TOKEN>",
    "url": "https://tudilink.com/p/<HANDOFF_TOKEN>",
    "status": "ready",
    "chargedCredits": 1,
    "replayed": false,
    "launchAttempts": 0,
    "editorReceivedAt": null,
    "publishedAt": null,
    "noteUrl": null,
    "confirmationSource": null
  }
}

幂等键与计费

成功创建交稿包时扣 1 次额度，保存与扣费在同一原子操作中完成。幂等范围是当前账号、同一个键和相同的规范化内容。

网络中断、超时或 5xx 不能证明服务端未完成创建。保留原文和原键重试，避免把未知结果变成重复扣费。

查询稿件

GET /api/v1/handoffs

支持 page 与 pageSize 分页，返回 items 和 total。撤销、记录收稿反馈和回填笔记链接在创建者的工作台操作。

curl -sS "$BASE/api/v1/handoffs?page=1&pageSize=30" \
  -H "Authorization: Bearer $NOTEHANDOFF_KEY"

状态语义

收稿和发布记录都不是小红书平台核验结果。

错误处理

结合 HTTP 状态、message 和 x-error-code 判断下一步；若返回 Retry-After，请按实际等待提示处理。

使用限制

• 标题最多 20 个中文等效字符，正文最多 1000 个 Unicode 码点。
• 交稿输入允许 1–18 张图片；实际 App 收稿需核对机型、版本及内容组合。
• 单图不超过 10 MiB、单边不超过 32768 像素、总像素不超过 8000 万。
• 每账户每天最多上传100张，另有站点资源限流，与购买次数独立。上传前需有可用次数；未成功创建交稿包不扣次数。
• 托管素材从上传起最长保存 7 天；交稿链接最长 7 天，且不会晚于其中最早到期的托管素材。重用图片不会延长其期限。
• 当前只支持图文，最终发布由使用者在小红书中确认。

通用 HTTP 节点

Coze、n8n、Dify 等工具可以通过通用 HTTP 节点接入。使用上传返回的地址，或你已有的有效公开 HTTPS 图片地址。

不要把每次重跑都会变化的执行 ID 当幂等键。具体节点界面以相应工具文档为准。