Install
npx skillscat add rnthking/redya-skills/redya-xiaohongshu Install via the SkillsCat registry.
红鸦开放平台:小红书图文生成
通过红鸦(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,几步就能拿到:
- 打开 https://hy.ithinkai.cn,用微信扫码登录
- 点左侧栏「红鸦 Skills」(或首页输入框上方的 🦞 红鸦 Skills 入口)
- 点「生成 API Key」,复制
rk-开头的 key(明文只显示这一次)- 回到这里设置环境变量:
export REDYA_API_KEY=rk-你复制的key(默认 base url 为 https://hy.ithinkai.cn,私有部署再设REDYA_BASE_URL)配好后告诉我,我继续帮你生成。
拿到 key 再进行后续流程;key 消耗的是该用户自己账号的积分。
核心交互原则(必读)
这一节决定了你作为 Agent 该怎么用这套 API,比接口细节更重要。
1. 默认走「分步模式」,别急着出图
一篇图文 = 一条 record。正确的默认流程:
POST /openapi/v1/outlines(不带auto)先生成大纲;- 把返回的标题、正文、每页图片说明用 markdown 排版展示给用户,征求意见;
- 用户用自然语言提修改意见(如"第 3 页换成对比图"、"标题再抓人一点")时,由你自己改好 pages JSON,调
PUT /openapi/v1/outlines/:record_id整组覆盖更新,再把改后的版本展示给用户; - 用户明确确认满意后,才调
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. 封面

2. 内容页
3. partial 时主动兜底
status: partial 表示部分页失败。查看 pages 里哪些页 status 为 failed,明确告诉用户是哪几页失败了,并询问是否要对失败页单页重生成(POST /openapi/v1/images/regenerate)。重生成同样是异步的,继续轮询同一条 record。
4. 用户给了链接:先解析,再改写
用户丢来一条小红书 / 抖音 / 公众号 / 快手 / B站链接(或整段分享口令)时,不要让他重新描述内容:
POST /openapi/v1/sources提交链接(扣 2 积分,解析失败不扣);- 每 5~10 秒轮询
GET /openapi/v1/sources/:source_id,直到status为ready或failed; - 拿到结果后先把原内容摘要给用户看(标题、作者、正文或口播文案前几句),确认是不是他要的那条;
POST /openapi/v1/outlines时带上source_id,原内容会作为参考资料进入生成。
要点:
- 视频类(抖音/快手/B站,以及小红书视频笔记)的价值在
transcript(口播文案)——阿里云语音识别转写的原视频人声。content_text往往很短甚至是空的; - 图文类(公众号、小红书图文)的价值在
content_text和images; transcript为空且content_type是video时,多半是纯 BGM 没有人声,如实告诉用户,别硬编;- 解析结果保留 72 小时,过期后
source_id失效,需要重新解析。
5. 知识库:先列出,再选用
用户说"参考我知识库里的资料"时:
GET /openapi/v1/knowledge-bases列出他的知识库,让他挑(或按名字自动匹配);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 实况
GET /openapi/v1/live-photos/capabilities查询可用模式、AI 模型、清晰度和积分报价。mode=live是免费镜头动效;mode=ai是 AI 自然动态,先展示当前报价并取得用户对收费制作的授权。- 为每张图生成并保存一个 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。 - 默认
action=natural。只给有要求的图片设置action=custom和该图的prompt;其他图保持自然微动。不要加入文章大纲、素材替换说明或商品用途作为动作指令。支持尾帧的 AI 模型可额外上传tail_image。 - 每 5–10 秒查询
GET /openapi/v1/live-photos/:request_id。同一请求重试沿用原 UUID 和参数,参数冲突返回 409;超时、断线、needs_review 时查原请求,不换编号重复提交。 - 提交结果待核实或服务重启后,可
POST /openapi/v1/live-photos/:request_id/recover恢复原任务;不会重新制作或再次扣视频积分。 - 完成后
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_4prompt_length(可选)short|long,默认shortproduct_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(可选)已完成的记录要整篇重出时传truecallback_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|errorpages[]每页: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 保护)。
- 生成内容的归属与合规责任由调用方承担,平台保留全部生成记录;涉及功效宣称、医疗等敏感品类时提醒用户自行把关文案合规。