使用红鸦 API 创作小红书图文、制作 Live 实况图片,或检测和修改文案敏感词;支持商品档案及个人词库。
通过红鸦(RedYA)开放平台 API,为用户生成完整的小红书图文笔记:标题 + 正文 + 多页配图。支持普通种草笔记与商品带货图文两种模式。
REDYA_API_KEY,值以 rk- 开头。每个请求通过 Authorization: Bearer $REDYA_API_KEY 传递(也可用 X-API-Key 头)。https://hy.ithinkai.cn,可用环境变量 REDYA_BASE_URL 覆盖。下文 curl 统一写作 ${REDYA_BASE_URL:-https://hy.ithinkai.cn}。api)。调用任何红鸦接口前,先确认环境里有 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,比接口细节更重要。
一篇图文 = 一条 record。正确的默认流程:
POST /openapi/v1/outlines(不带 auto)先生成大纲;PUT /openapi/v1/outlines/:record_id 整组覆盖更新,再把改后的版本展示给用户;POST /openapi/v1/images 出图。只有当用户明确说"直接出"、"一步到位"、"不用给我看大纲"之类时,才在 outlines 请求里带 auto: true,让大纲完成后立即整篇出图。
提交出图后拿到 task_id,接着每 15~30 秒调一次 GET /openapi/v1/records/:record_id,直到 status 进入终态之一:completed / partial / error。出图通常需要 1~5 分钟,轮询期间可以告知用户进度(已完成几页)。
拿到结果后,把每页图片以 markdown 图片列表呈现给用户:
1. 封面

2. 内容页

partial 时主动兜底status: partial 表示部分页失败。查看 pages 里哪些页 status 为 failed,明确告诉用户是哪几页失败了,并询问是否要对失败页单页重生成(POST /openapi/v1/images/regenerate)。重生成同样是异步的,继续轮询同一条 record。
用户丢来一条小红书 / 抖音 / 公众号 / 快手 / B站链接(或整段分享口令)时,不要让他重新描述内容:
POST /openapi/v1/sources 提交链接(扣 2 积分,解析失败不扣);GET /openapi/v1/sources/:source_id,直到 status 为 ready 或 failed;POST /openapi/v1/outlines 时带上 source_id,原内容会作为参考资料进入生成。要点:
transcript(口播文案)——阿里云语音识别转写的原视频人声。content_text 往往很短甚至是空的;content_text 和 images;transcript 为空且 content_type 是 video 时,多半是纯 BGM 没有人声,如实告诉用户,别硬编;source_id 失效,需要重新解析。用户说"参考我知识库里的资料"时:
GET /openapi/v1/knowledge-bases 列出他的知识库,让他挑(或按名字自动匹配);POST /openapi/v1/outlines 带 knowledge_base_ids(数组,最多 5 个)。生成时会用用户的 topic 去这些知识库里检索最相关的片段注入提示词。用户没提知识库就别自作主张带上——检索出的资料会影响文案走向。
POST /openapi/v1/products 一键建档,拿到 product_id;POST /openapi/v1/outlines 时带上 product_id(style 会自动用带货风格,无需手动指定);GET /openapi/v1/skills 列出带货 Skill 让用户挑,outlines 时带 skill_id;GET /openapi/v1/products 看看账号下是否已有建好档的商品可直接复用。中文 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 请求。不要猜字补回,不要切换模型或重复提交同一份乱码。
---
仅转实况或检测文案时,直接使用下面的工具接口,不要先生成图文大纲。所有调用沿用用户自己的 API Key。以下接口无需先创建图文大纲。
GET /openapi/v1/live-photos/capabilities 查询可用模式、AI 模型、清晰度和积分报价。mode=live 是免费镜头动效;mode=ai 是 AI 自然动态,先展示当前报价并取得用户对收费制作的授权。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。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]}。只操作本人词库,不扣检测积分。---
用途:根据主题生成小红书图文大纲(标题 + 正文 + 每页图片说明)。同步接口,通常秒级~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 为 draftauto=true 时额外返回 task_id、pages_submitted、images_points_cost,status 为 generating_images;若出图提交失败,大纲照常返回并附 images_error(此时可稍后手动调 /images)。
用途:按用户修改意见更新大纲。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,不可编辑。
用途:对已确认的大纲整篇出图。积分在提交时按页数预扣,提交/生成失败自动退款。
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"}
用途:查询生成进度与结果。建议轮询间隔 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_atpartial = 部分页失败,失败页可单独重生成。图片 URL 为 COS 直链,建议 7 天内转存。
用途:对 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。
用途:用商品图片 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")。
用途:列出账号下已建档商品,用户没给新图时可从中复用。
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,...}]}
用途:列出带货文案风格 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":"像自己用过的分享,不硬推"}]}
把一条平台链接解析成可复用的文案素材。每次成功解析扣 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}
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 地址带签名且校验来源,拿到也用不了。
响应:{"list":[{"knowledge_base_id":"folder_xxx","name":"护肤材料"}]}
拿到的 knowledge_base_id 用于 POST /outlines 的 knowledge_base_ids。
用途:查积分余额、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 的请求先查记录状态,避免结果未确认就重复出图 |
PUT /outlines/:id 的 pages 必须 1~15 页。--max-time 360。5 分钟是最长等待时间,不是每次都要等满。Weekly roundup of top Claude Code skills, MCP servers, and AI coding tips.