rnthking

redya-xiaohongshu

使用红鸦 API 创作小红书图文、制作 Live 实况图片,或检测和修改文案敏感词;支持商品档案及个人词库。

rnthking 19 3 Updated 1w ago
GitHub

Install

npx skillscat add rnthking/redya-skills/redya-xiaohongshu

Install via the SkillsCat registry.

SKILL.md

红鸦开放平台:小红书图文生成

通过红鸦(RedYA)开放平台 API,为用户生成完整的小红书图文笔记:标题 + 正文 + 多页配图。支持普通种草笔记与商品带货图文两种模式。

前置条件

  • API Key:需要环境变量 REDYA_API_KEY,值以 rk- 开头。每个请求通过 Authorization: Bearer $REDYA_API_KEY 传递(也可用 X-API-Key 头)。
  • Base URL:默认 https://hy.ithinkai.cn,可用环境变量 REDYA_BASE_URL 覆盖。下文 curl 统一写作 ${REDYA_BASE_URL:-https://hy.ithinkai.cn}。
  • 计费:与网页端同价——大纲按次(默认 2 积分),图片按张(默认 5 积分/张),生成失败自动退款。消耗绑定账号的积分,生成记录在网页端「我的创作」可见(来源标记 api)。

⚠️ 第一步(必做):确认有可用的 API Key

调用任何红鸦接口前,先确认环境里有 REDYA_API_KEY(以 rk- 开头)。没有、或任何接口返回 401,就停下来引导用户自助创建,不要瞎猜、不要反复重试。 直接对用户说(可照抄):

你还没配置红鸦 API Key,几步就能拿到:

  1. 打开 https://hy.ithinkai.cn,用微信扫码登录
  2. 点左侧栏「红鸦 Skills」(或首页输入框上方的 🦞 红鸦 Skills 入口)
  3. 点「生成 API Key」,复制 rk- 开头的 key(明文只显示这一次)
  4. 回到这里设置环境变量:export REDYA_API_KEY=rk-你复制的key(默认 base url 为 https://hy.ithinkai.cn,私有部署再设 REDYA_BASE_URL)

配好后告诉我,我继续帮你生成。

拿到 key 再进行后续流程;key 消耗的是该用户自己账号的积分。

核心交互原则(必读)

这一节决定了你作为 Agent 该怎么用这套 API,比接口细节更重要。

1. 默认走「分步模式」,别急着出图

一篇图文 = 一条 record。正确的默认流程:

  1. POST /openapi/v1/outlines(不带 auto)先生成大纲;
  2. 把返回的标题、正文、每页图片说明用 markdown 排版展示给用户,征求意见;
  3. 用户用自然语言提修改意见(如"第 3 页换成对比图"、"标题再抓人一点")时,由你自己改好 pages JSON,调 PUT /openapi/v1/outlines/:record_id 整组覆盖更新,再把改后的版本展示给用户;
  4. 用户明确确认满意后,才调 POST /openapi/v1/images 出图。

只有当用户明确说"直接出"、"一步到位"、"不用给我看大纲"之类时,才在 outlines 请求里带 auto: true,让大纲完成后立即整篇出图。

2. 出图是异步的,靠轮询拿结果

提交出图后拿到 task_id,接着每 15~30 秒调一次 GET /openapi/v1/records/:record_id,直到 status 进入终态之一:completed / partial / error。出图通常需要 1~5 分钟,轮询期间可以告知用户进度(已完成几页)。

拿到结果后,把每页图片以 markdown 图片列表呈现给用户:

1. 封面
   ![第1页](https://cos.../task_x/0.png)
2. 内容页
   ![第2页](https://cos.../task_x/1.png)

3. partial 时主动兜底

status: partial 表示部分页失败。查看 pages 里哪些页 status 为 failed,明确告诉用户是哪几页失败了,并询问是否要对失败页单页重生成(POST /openapi/v1/images/regenerate)。重生成同样是异步的,继续轮询同一条 record。

4. 用户给了链接:先解析,再改写

用户丢来一条小红书 / 抖音 / 公众号 / 快手 / B站链接(或整段分享口令)时,不要让他重新描述内容:

  1. POST /openapi/v1/sources 提交链接(扣 2 积分,解析失败不扣);
  2. 每 5~10 秒轮询 GET /openapi/v1/sources/:source_id,直到 status 为 ready 或 failed;
  3. 拿到结果后先把原内容摘要给用户看(标题、作者、正文或口播文案前几句),确认是不是他要的那条;
  4. POST /openapi/v1/outlines 时带上 source_id,原内容会作为参考资料进入生成。

要点:

  • 视频类(抖音/快手/B站,以及小红书视频笔记)的价值在 transcript(口播文案)——阿里云语音识别转写的原视频人声。content_text 往往很短甚至是空的;
  • 图文类(公众号、小红书图文)的价值在 content_text 和 images;
  • transcript 为空且 content_type 是 video 时,多半是纯 BGM 没有人声,如实告诉用户,别硬编;
  • 解析结果保留 72 小时,过期后 source_id 失效,需要重新解析。

5. 知识库:先列出,再选用

用户说"参考我知识库里的资料"时:

  1. GET /openapi/v1/knowledge-bases 列出他的知识库,让他挑(或按名字自动匹配);
  2. POST /openapi/v1/outlines 带 knowledge_base_ids(数组,最多 5 个)。

生成时会用用户的 topic 去这些知识库里检索最相关的片段注入提示词。用户没提知识库就别自作主张带上——检索出的资料会影响文案走向。

6. 商品带货:先建档,再创作

  • 用户给了商品图 URL → 先调 POST /openapi/v1/products 一键建档,拿到 product_id;
  • 然后 POST /openapi/v1/outlines 时带上 product_id(style 会自动用带货风格,无需手动指定);
  • 可选:先 GET /openapi/v1/skills 列出带货 Skill 让用户挑,outlines 时带 skill_id;
  • 用户想做商品带货但没给商品图时,提醒用户:商品图文必须提供商品图片 URL(http/https 直链,1~30 张),或者用 GET /openapi/v1/products 看看账号下是否已有建好档的商品可直接复用。

7. 中文请求使用 UTF-8,编辑后核对保存结果

中文 JSON 直接由程序序列化为 UTF-8 发送。用 curl 时,先把请求写入 UTF-8 文件,再用 --data-binary @request.json;不要经由系统默认编码或 ASCII 转码的命令行管道。仅设置请求头不能修复已变成问号的文字。

例如,用 Python 保存请求文件:

import json
from pathlib import Path
payload = {"topic": "三伏天养生茶推荐", "style": "xiaohongshu_2"}
Path("request.json").write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")

然后发送(Windows PowerShell 请把下方命令改为 curl.exe,使用自己的变量语法或填入完整 URL 和 Key):

curl -sS --max-time 360 "${REDYA_BASE_URL:-https://hy.ithinkai.cn}/openapi/v1/outlines" \
  -H "Authorization: Bearer $REDYA_API_KEY" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data-binary @request.json

编辑大纲后,先 GET /openapi/v1/records/:record_id 核对标题、正文和每页说明与用户确认版本一致,再提交生图。接口返回 422 invalid_text_encoding 表示检测到无效字符或大量替代问号:保留原稿、不扣费,从用户原文或正常备份重新构造 UTF-8 请求。不要猜字补回,不要切换模型或重复提交同一份乱码。


实况图与敏感词检测(1.6.1)

仅转实况或检测文案时,直接使用下面的工具接口,不要先生成图文大纲。所有调用沿用用户自己的 API Key。以下接口无需先创建图文大纲。

图片转 Live 实况

  1. GET /openapi/v1/live-photos/capabilities 查询可用模式、AI 模型、清晰度和积分报价。mode=live 是免费镜头动效;mode=ai 是 AI 自然动态,先展示当前报价并取得用户对收费制作的授权。
  2. 为每张图生成并保存一个 UUID request_id,以 multipart/form-data 调 POST /openapi/v1/live-photos:必填 request_id、图片文件 image;选填 mode(默认 live)、effect(0–12)。AI 再传 model_code、quality、当前报价 expected_points。
  3. 默认 action=natural。只给有要求的图片设置 action=custom 和该图的 prompt;其他图保持自然微动。不要加入文章大纲、素材替换说明或商品用途作为动作指令。支持尾帧的 AI 模型可额外上传 tail_image。
  4. 每 5–10 秒查询 GET /openapi/v1/live-photos/:request_id。同一请求重试沿用原 UUID 和参数,参数冲突返回 409;超时、断线、needs_review 时查原请求,不换编号重复提交。
  5. 提交结果待核实或服务重启后,可 POST /openapi/v1/live-photos/:request_id/recover 恢复原任务;不会重新制作或再次扣视频积分。
  6. 完成后 GET /openapi/v1/live-photos/:request_id/content?format=pvt 下载,格式还包括 mp4、photo、ios、android、mac、windows。返回的下载路径需要拼接 Base URL 并携带 Key;先保存本地再交付,不能当作匿名公开图片链接。
# REQUEST_ID 在首次制作前生成并保存,重试复用。
curl --fail --max-time 120 "${REDYA_BASE_URL:-https://hy.ithinkai.cn}/openapi/v1/live-photos" \
  -H "Authorization: Bearer $REDYA_API_KEY" \
  -F "request_id=$REQUEST_ID" -F 'mode=live' -F 'effect=0' -F 'image=@/absolute/path/photo.jpg'

批量处理时保存每张图片对应的 UUID。静置物品或场景识别不确定时,服务会使用整幅同步微动保护,不调用收费视频生成;最终费用查看 video_points。保存教程:https://hy.ithinkai.cn/tools/live-photo/save 。下载成功不能表述成已导入手机实况相册。

敏感词检测与修改

  • GET /openapi/v1/content-review/status 查看配置及 points_per_check。费用与网页一致,先告知用户;失败不收费,缓存结果以 charged_points 为准。
  • POST /openapi/v1/content-review,JSON:{"fields":[{"id":"title","label":"标题","text":"待检查标题"},{"id":"body","label":"正文","text":"待检查正文"}]}。每次 1–64 段、共 1–30000 字,中文 JSON 必须 UTF-8。
  • 展示 findings 中的原词、原因和替换建议,让用户确认修改范围。检测不等于平台审核通过,不自动发布。
  • 用户确认后,POST /openapi/v1/content-review/replace,携带原样的 fields、完整原始检测结果 review、选中的 finding_ids、action=replace 或 delete,以及可选 choices(finding.id 到替换词)。服务校验签名、原文及账号,不自行拼造检测结果。
  • 用户明确要求管理个人词库时才使用:GET /openapi/v1/sensitive-words;PUT 提交 {"words":[{"word":"词语","replacement":"替换词","level":"medium","reason":"说明"}]};DELETE 提交 {"ids":[词条ID]}。只操作本人词库,不扣检测积分。

接口速查

POST /openapi/v1/outlines — 生成大纲(同步)

用途:根据主题生成小红书图文大纲(标题 + 正文 + 每页图片说明)。同步接口,通常秒级~1 分钟返回,复杂内容可能更久。服务端总超时上限 5 分钟(包含渠道切换),curl 请带 --max-time 360,为返回和保存结果留出余量。

文本渠道按网页后台对应创作模式的当前配置调用。普通图文与商品图文分别使用各自的渠道列表,按配置顺序选择;遇到 503、额度不足等明确的渠道失败时切换下一项,单次大纲最多调用 3 个渠道。不会因格式检查失败反复重写或自动补全。旧版 Skill 传入的 xiaohongshu_2、xiaohongshu_3、xiaohongshu_4 继续兼容,无需为了渠道修复重新安装。style 不用于指定文本渠道,默认输出上限为 16000 tokens(可由管理员按渠道配置覆盖)。

curl -sS --max-time 360 -X POST "${REDYA_BASE_URL:-https://hy.ithinkai.cn}/openapi/v1/outlines" \
  -H "Authorization: Bearer $REDYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "三伏天养生茶推荐",
    "style": "xiaohongshu_2",
    "prompt_length": "short"
  }'

请求字段:

  • topic(必填)创作主题
  • style(可选)风格。默认:普通=xiaohongshu_2,带货=xiaohongshu_4
  • prompt_length(可选)short|long,默认 short
  • product_id(可选)商品图文模式必传(见 /products)
  • skill_id(可选)带货 Skill(见 /skills)
  • image_urls(可选)参考图 URL 数组(普通模式)
  • source_id(可选)先用 POST /sources 解析链接拿到的 ID,原内容会作为参考资料进入生成
  • knowledge_base_ids(可选)知识库 ID 数组,最多 5 个(见 /knowledge-bases)。用户没提就别带
  • auto(可选)true = 大纲完成后立即整篇出图
  • callback_url(可选)auto 时出图完成后 webhook 回调

响应关键字段(auto=false):

  • record_id 本篇图文唯一标识,后续所有操作都用它
  • title / content 标题与小红书正文
  • pages[] 每页说明:index、type(cover/content)、content(图片说明);商品模式还有 matched_image_id(配图 id)
  • points_cost 本次扣的积分
  • status 为 draft

auto=true 时额外返回 task_id、pages_submitted、images_points_cost,status 为 generating_images;若出图提交失败,大纲照常返回并附 images_error(此时可稍后手动调 /images)。

PUT /openapi/v1/outlines/:record_id — 编辑大纲

用途:按用户修改意见更新大纲。pages 是整组覆盖(1~15 页),要把没改的页也原样带上。

curl -sS -X PUT "${REDYA_BASE_URL:-https://hy.ithinkai.cn}/openapi/v1/outlines/5fb16b40-xxxx" \
  -H "Authorization: Bearer $REDYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "新标题",
    "content": "新正文",
    "pages": [
      {"index": 0, "type": "cover", "content": "改后的封面说明"},
      {"index": 1, "type": "content", "content": "第二页说明"}
    ]
  }'

请求字段:pages(必填,整组覆盖)、title(可选)、content(可选)。

响应:{"record_id":"...","updated":true,"pages":5}。图片生成中时返回 409,不可编辑。

POST /openapi/v1/images — 整篇出图(异步)

用途:对已确认的大纲整篇出图。积分在提交时按页数预扣,提交/生成失败自动退款。

curl -sS -X POST "${REDYA_BASE_URL:-https://hy.ithinkai.cn}/openapi/v1/images" \
  -H "Authorization: Bearer $REDYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "record_id": "5fb16b40-xxxx"
  }'

请求字段:

  • record_id(必填)
  • product_id 商品图文必传(记录若之前出过商品图会自动继承)
  • skill_id(可选)
  • image_urls(可选)参考图;缺省沿用大纲阶段的
  • force(可选)已完成的记录要整篇重出时传 true
  • callback_url(可选)完成后 webhook

响应:{"record_id":"...","task_id":"task_ab12cd34","pages_submitted":5,"points_cost":25,"status":"generating_images"}

GET /openapi/v1/records/:record_id — 状态轮询

用途:查询生成进度与结果。建议轮询间隔 15~30 秒。

curl -sS "${REDYA_BASE_URL:-https://hy.ithinkai.cn}/openapi/v1/records/5fb16b40-xxxx" \
  -H "Authorization: Bearer $REDYA_API_KEY"

响应关键字段:

  • status 整篇状态:draft | generating_outline | generating_images | completed | partial | error
  • pages[] 每页:index、type、content、status(not_generated/completed/generating/failed)、image_url(COS 直链,失败/未完成为空串)
  • title / content / style / source(api)/ page_count / created_at

partial = 部分页失败,失败页可单独重生成。图片 URL 为 COS 直链,建议 7 天内转存。

POST /openapi/v1/images/regenerate — 单页重生成(异步)

用途:对 failed(或用户不满意)的单页重出图。商品图文自动继承原商品信息。

curl -sS -X POST "${REDYA_BASE_URL:-https://hy.ithinkai.cn}/openapi/v1/images/regenerate" \
  -H "Authorization: Bearer $REDYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "record_id": "5fb16b40-xxxx",
    "page_index": 2
  }'

请求字段:record_id、page_index,可选 callback_url。

响应:{"record_id":"...","page_index":2,"next_filename":"2_1.png","points_cost":5,"status":"generating"}。该页生成中时返回 409。完成与否继续轮询 GET /records/:record_id。

POST /openapi/v1/products — 商品建档(带货前置)

用途:用商品图片 URL 一键建立商品档案,拿 product_id 供 outlines/images 使用。

curl -sS -X POST "${REDYA_BASE_URL:-https://hy.ithinkai.cn}/openapi/v1/products" \
  -H "Authorization: Bearer $REDYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "蓝金貔貅摆件",
    "image_urls": ["https://example.com/1.jpg", "https://example.com/2.jpg"],
    "labels": ["完整商品图", "质地细节图"]
  }'

请求字段:

  • name(必填)商品名
  • image_urls(必填)1~30 张,必须 http(s) 直链
  • labels(可选)与图片一一对齐;缺省全部按"完整商品图"
  • brand / category / selling_points(数组)/ source_ref 均可选

标签枚举:完整商品图/包装图/多角度图/套装组合图/质地细节图/其他细节图/工艺做工图/产品颜色图/尺寸规格图/模特上身图/使用对比图/使用步骤图/场景图/买家秀真实图/功能卖点图/成分配料图/资质认证图/其他

响应:{"product_id":36,"name":"...","material_count":2}。注意 product_id 在 outlines/images 里以字符串传入(如 "36")。

GET /openapi/v1/products — 我的商品档案

用途:列出账号下已建档商品,用户没给新图时可从中复用。

curl -sS "${REDYA_BASE_URL:-https://hy.ithinkai.cn}/openapi/v1/products" \
  -H "Authorization: Bearer $REDYA_API_KEY"

响应:{"products":[{"product_id":36,"name":"...","cover_image":"...","material_count":2,...}]}

GET /openapi/v1/skills — 可用带货 Skill

用途:列出带货文案风格 Skill,可展示给用户挑选后在 outlines 里传 skill_id。

curl -sS "${REDYA_BASE_URL:-https://hy.ithinkai.cn}/openapi/v1/skills" \
  -H "Authorization: Bearer $REDYA_API_KEY"

响应:{"skills":[{"skill_id":"real_exp","name":"真实体验种草","one_liner":"像自己用过的分享,不硬推"}]}

POST /openapi/v1/sources — 链接解析(异步)

把一条平台链接解析成可复用的文案素材。每次成功解析扣 2 积分,失败不扣。

请求:

{ "url": "https://v.douyin.com/xxxxx/" }

url 可以是纯链接,也可以直接把整段分享口令粘进来(如 7.41 复制打开抖音,看看【...】 https://v.douyin.com/xxx/),服务端会自己提取。

支持的平台:小红书(xiaohongshu.com / xhslink.com / xhslink.cn)、抖音(douyin.com)、公众号(mp.weixin.qq.com)、快手(kuaishou.com)、B站(bilibili.com / b23.tv)。

响应:{"source_id":"src_...","platform":"douyin","content_type":"video","status":"pending","points_cost":2}

GET /openapi/v1/sources/:source_id — 解析结果轮询

status:pending → processing → ready / failed。每 5~10 秒轮一次,通常 20~60 秒完成(视频要下载+转写,可能到 2 分钟)。

ready 时的响应:

{
  "source_id": "src_...",
  "platform": "douyin",
  "content_type": "video",
  "status": "ready",
  "title": "...",
  "author": "...",
  "content_text": "原文案(图文类是正文,视频类常常很短或为空)",
  "transcript": "口播文案:视频人声的逐句转写",
  "images": ["https://.../content-sources/src_x/media/0"],
  "video_url": "https://.../content-sources/src_x/video",
  "original_url": "https://v.douyin.com/xxxxx/"
}

failed 时看 error 字段,原样转述给用户。常见原因:链接失效、平台风控、视频没有人声。

images 和 video_url 是带鉴权的代理地址,直接展示给用户即可;平台原始 CDN 地址带签名且校验来源,拿到也用不了。

GET /openapi/v1/knowledge-bases — 我的知识库

响应:{"list":[{"knowledge_base_id":"folder_xxx","name":"护肤材料"}]}

拿到的 knowledge_base_id 用于 POST /outlines 的 knowledge_base_ids。

GET /openapi/v1/me — 账户信息

用途:查积分余额、key 信息与今日配额。402/429 时先调它再向用户说明。

curl -sS "${REDYA_BASE_URL:-https://hy.ithinkai.cn}/openapi/v1/me" \
  -H "Authorization: Bearer $REDYA_API_KEY"

响应:{"user_id":3528,"nickname":"...","points_balance":355,"key_name":"...","key_prefix":"rk-1a2b3c4d","daily_quota":100,"used_today":12}


错误处理

非 2xx 统一返回 {"error":{"code":"...","message":"..."}}。按状态码处置:

状态码 code Agent 该怎么做
401 missing_key/invalid_key/key_disabled/key_expired/user_disabled Key 缺失或无效。引导用户自助创建(见下方「没有 Key 怎么办」):访问 https://hy.ithinkai.cn 微信登录 → 左栏「红鸦 Skills」→「生成 API Key」→ 复制后 export REDYA_API_KEY=rk-xxx。不要反复重试或猜测 key
402 insufficient_points 积分不足。调 GET /me 拿 points_balance 告诉用户当前余额,引导用户去红鸦网页端充值后再继续
403 forbidden 访问了他人资源,检查 record_id/product_id 是否属于当前 key 的账号
404 not_found 资源不存在,检查 id 是否拼错
409 conflict 生成中(或已完成)。不是错误——继续轮询 GET /records/:id 等终态;整篇重出已完成记录用 force: true
422 invalid_request 参数错误,按 message 修正请求体
422 invalid_text_encoding 中文编码疑似损坏。原稿不覆盖、不扣费;按上面的 UTF-8 说明从正常原文重新发送,不要继续生图
429 quota_exceeded 今日配额用尽。告诉用户该 key 的日生成配额已用完(可用 GET /me 看 daily_quota/used_today),明天再试或找管理员调额
5xx — 大纲服务已按配置尝试渠道切换。仍失败时报告具体原因,不要自动连续重提;已有 record_id 的请求先查记录状态,避免结果未确认就重复出图

注意事项

  • 单篇最多 15 页;PUT /outlines/:id 的 pages 必须 1~15 页。
  • 大纲接口是同步的,服务端总超时上限 5 分钟,包含渠道切换;curl 请带 --max-time 360。5 分钟是最长等待时间,不是每次都要等满。
  • 图片 URL 是 COS 直链,建议 7 天内转存到用户自己的存储,长期引用别依赖原链接。
  • 请勿并发对同一 record 提交出图(有 409 保护)。
  • 生成内容的归属与合规责任由调用方承担,平台保留全部生成记录;涉及功效宣称、医疗等敏感品类时提醒用户自行把关文案合规。