探索 xPosts ↗
DOCUMENTATION / 文档中心

xPosts 使用与接入文档

从首次创作到程序接入,在一页找到操作步骤、接口参数与积分规则。

查找文档

第一次使用:完成一个可追踪的任务

  1. 登录并确认权益使用你的 xPosts 账号进入工作台。在钱包查看可用积分和套餐周期,需要时主动购买。
  2. 选择目标与能力创作工作室用于图片和视频;社媒洞察用于平台查询。先选模型或平台操作,再填写出现的条件。
  3. 核对输入和费用确认提示词、素材、输出规格和报价。参数不完整时先修正表单,不重复点击提交。
  4. 查看并复用结果任务记录展示真实状态。完成的媒体进入素材与作品,查询任务可查看返回结果并保存样本。
按业务目标选择流程

从业务目标,找到对应流程

你的目标准备什么如何做与得到什么
电商商品图、活动封面商品图、品牌色、用途和画面比例图片创作,得到可检查和下载的视觉素材
社媒选题、竞品内容研究平台、关键词或公开内容 / 账号链接查询并保存样本,查看内容、创作者、评论等可用字段及统计
借鉴热门视频的表达方式有权使用的参考视频、自己的主体与素材关键帧分析与提示词反推,再生成自己的短片
商品动态展示、创意镜头一个主体、动作与镜头方向,必要的参考素材视频生成,得到 4–5 秒无音频短片素材
在 AI 助手里持续创作支持扩展的客户端、xPosts 账号与相应权益连接客户端,由助手调用并追踪同一工作台的任务

查看完整场景、示例提示词和费用说明 ↗

跟着做:生成第一张图片

准备:已登录账号、有效订阅、足以覆盖本次报价的可用积分。使用参考图时,先确保素材已经上传并通过校验。

  1. 进入创作工作室,选择图片选择 GPT Image 2,检查画面比例、质量与当前固定 1K 输出规格。
  2. 描述主体、用途与画面例如:“制作一张咖啡店春季上新海报的背景图,柔和自然光、浅绿色植物,主体为白色咖啡杯,右侧预留标题空间,不添加文字。”
  3. 按需加入参考图最多 4 张参考图;使用蒙版时可另加 1 张 PNG 蒙版。具体要求见素材限制。没有参考图也可以从文字开始。
  4. 确认报价并提交当前每任务 1 张,积分按所选参数报价。提交后会预留积分,记下任务编号。
  5. 查看结果并下载在任务记录查看状态,成功后到素材与作品查看生成图。检查商品细节和文字后再使用;重新生成会创建新的收费任务。

打开图片创作 ↗ · 全部图片参数 ↗

图片模型参数与参考要求

图片:把画面描述变成可复用素材

当前图片模型为 GPT Image 2。适合商品展示、社媒封面、场景概念与视觉方案;生成内容仍需由你检查文字、细节与使用权。

条件当前支持
输出1K,每任务 1 张
画面比例1:1、16:9、9:16、4:3
质量low、medium、high,以工作台可选项为准
参考素材最多 4 张参考图,可另加 1 张同尺寸 PNG 蒙版
提示词1–8,000 字符
费用按模型参数报价,提交前展示报价
  1. 描述画面写清主体、用途、构图、色调和不希望出现的元素。
  2. 设置条件选择比例与质量;需要参考时先上传并确认素材可用。
  3. 确认并生成核对报价后提交,在任务记录查看进度,完成后下载或复用作品。
提示词与输出规格检查

图片与视频:提交前的检查

提示词写清“画面要发生什么”

主体、场景、构图、风格与用途是图片描述的基础;视频还应写出动作、镜头运动与节奏。避免把互相冲突的要求堆在一起。

查看指南 ↗

条件以所选模型为准

切换模型后重新检查比例、时长与参考素材。当前视频为固定 480p 短片,图片为 1K;不能通过自由文本强制启用未开放的输出规格。

查看指南 ↗
示例:商品与品牌视觉

商品与品牌视觉

准备一张可用的商品参考图、品牌色与画面用途。

示例任务
为这款白色保温杯制作一张 1:1 商品主视觉:浅灰背景,柔和自然光,突出杯身材质,保留商品外观,不添加未经提供的文字。

操作路径

在创作工作室选择图片模型,上传参考图,选择比例,确认本次积分报价后生成。

产出与费用

获得 1 张 1K 图片,检查商品细节、文字和品牌一致性后使用。

参考素材只能帮助表达方向,不保证逐像素复刻。

示例:封面与活动海报

社媒封面与活动海报

准备主题、目标受众、画面比例与希望预留的文字位置。

示例任务
生成一张适合春日城市漫步的竖版封面,清新自然光,画面下方预留标题区域,以街角咖啡馆和绿植为主体。

操作路径

按发布位置选 9:16 或其他可用比例,先生成一版,再按结果调整提示词。

产出与费用

图片任务按模型与参数报价;多次修改重新生成会分别计费。

最终标题与文字需自行核对,平台不代为发布。

跟着做:生成第一条短视频

准备:已登录账号、有效订阅及足以覆盖本次报价的可用积分;选择需要参考素材的模型时,先准备有权使用的素材。

  1. 选择视频模型Grok Imagine Video 1.5 当前为 480p、5 秒;Seedance 2 Mini 为 480p、4 秒、16:9,必须提供参考素材,最多3张图片+1段视频,至少1项。两者当前均不生成音频。
  2. 描述一个清晰镜头例如:“暖色晨光下的咖啡杯特写,蒸汽缓慢升起,镜头轻轻推进,背景简洁。”短片优先安排单一动作,避免过多场景切换。
  3. 核对条件和报价切换模型后重新检查输入。按工作台可用规格设置,不通过提示词强制要求未开放的时长或分辨率。
  4. 提交后查看任务不需要一直打开生成页。成功后查看短片、下载素材,再自行完成配乐或后续剪辑。

打开视频创作 ↗ · 长时间等待或失败如何处理 ↗

视频模型规格与参考要求

视频:先选模型,再确定创作条件

不同模型的输入要求不同。当前开放固定短片规格,不能把所有模型的条件混用;不承诺固定完成时间。

模型输出规格输入与用途积分
Grok Imagine Video 1.5480p · 5 秒 · 无音频提示词输入;当前不支持参考图片或视频按模型参数报价
Seedance 2 Mini480p · 4 秒 · 16:9 · 无音频必须提供参考素材及提示词;最多3张图片+1段视频,至少1项按模型参数报价

提交前检查镜头运动、主体动作和画面比例。素材类型、大小与组合限制以所选模型的表单校验为准。长片剪辑、音乐制作与自动发布不属于当前视频生成范围。

示例:短视频镜头

短视频镜头与动态素材

明确一个动作、一个主体与一个镜头变化,避免在数秒内安排过多情节。

示例任务
制作一个清晨咖啡杯特写镜头,镜头缓慢推进,蒸汽轻轻升起,暖色自然光,背景保持安静。

操作路径

选择 Grok Imagine Video 1.5,检查条件和报价,提交后通过任务编号跟踪。

产出与费用

当前规格为 480p、5 秒、无音频,按模型参数报价。

这是短片素材生成;长片剪辑、配乐与自动分发需另行完成。

示例:参考素材创作

围绕已有素材继续创作

准备你有权使用的参考素材:最多3张图片+1段视频,至少1项。

示例任务
沿用参考素材的主体和视觉方向,生成一个 4 秒横屏镜头;保持主体清晰,加入缓慢平移的镜头运动。

操作路径

选择 Seedance 2 Mini,等待参考素材校验完成,再填写提示词并核对输出规格。

产出与费用

当前规格为 16:9、480p、4 秒、无音频,按模型参数报价。

参考素材必填;文件类型与组合必须通过当前模型校验。

跟着做:分析并复刻参考视频

这里的复刻是借鉴画面与表达方法,结合自己的素材重新创作,不是搬运原片或承诺相同流量。

  1. 选择视频创作,打开素材反推在创作工作室选择「从素材反推提示词」。如果提示词服务未启用,可先手动描述参考画面。
  2. 选取参考视频的关键帧选择本机素材或可访问的素材。浏览器生成预览后,勾选准备分析的关键帧,并确认发送内容。
  3. 检查分镜计划与可编辑建议保留有用的主体、光线、构图与镜头表达,替换为你的产品和目标。关键帧未捕捉的动作、口播与音乐需要自行补充。
  4. 应用描述并重新生成加入模型要求的参考素材,核对当前短片规格与 本次积分报价,再提交任务。

查看创意改编示例 ↗ · 了解复刻能力边界 ↗

示例:参考视频与创意改编

爆款视频复刻与创意改编

准备一段你有权使用的参考视频,确定想借鉴的是构图、镜头氛围还是商品展示方式。把参考方法迁移到自己的内容,而不是直接搬运成片。

示例任务
分析我选中的参考视频关键帧,整理主体、光线、构图与镜头风格。把主体改为我的咖啡产品,形成一段适合短片生成的提示词;我确认条件和费用后再生成。

操作路径

创作工作室 → 从素材反推提示词 → 选择视频与关键帧 → 确认分析 → 调整描述与参考素材 → 选择视频模型生成。

产出与费用

先得到可编辑的参考描述,再创建自己的生成任务。视频按所选模型与参数报价;提示词分析的可用性和相关提示以工作台为准。

关键帧分析不涵盖完整口播、音乐和所有动作。生成的是 4–5 秒无音频短片,不承诺一键原样还原、自动剪成长片或获得同等流量。

上传、保存与下载素材

在素材与作品上传文件,等待校验完成后再用作参考。文件扩展名、媒体类型、大小和模型要求需匹配;不要通过改后缀绕过格式要求。

参考素材

引用当前账号可访问且已经就绪的素材。使用涉及人物、品牌或受版权保护内容的素材前,确认你拥有相应使用授权。

下载与分享

媒体存放在私有存储中,访问链接具有有效期。链接过期后回到作品重新获取;临时下载地址不适合作为永久外链。

素材格式、大小与参考限制

用途当前限制
上传至素材库JPEG、PNG、WebP 图片,每张不超过20 MiB;MP4 视频不超过100 MiB。上传成功后须等待状态变为 ready。
图片生成参考最多4张参考图,每张不超过20 MiB;可另加1张PNG蒙版,需与第一张原图尺寸一致。全部素材合计不超过25 MiB。
Seedance 视频生成参考最多3张参考图,每张不超过5 MiB;最多1段MP4参考视频,不超过20 MiB、15秒;全部素材合计不超过35 MiB,至少提供1项。
真实人物参考使用参考视频时需明确填写是否包含真实人物。参考视频服务不可用时,可改用符合条件的参考图片。

1 MiB = 1,048,576 字节。素材库上传上限与生成参考上限不同;通过上传校验不代表适用于所有模型。

查询社媒:先选操作,再提供标识

  1. 选择平台与操作平台间支持范围不同。搜索通常需要关键词;详情、账号或评论操作可能要求链接或标识。
  2. 阅读当前批次结果字段取决于平台返回。空结果、字段缺失与请求失败是不同状态,不把缺失指标当成真实零值。
  3. 需要更多结果,再继续查询下一页是新的收费查询,使用页面提供的分页条件。查询次数不等于内容条数。
  4. 保存有用样本,再看统计只分析已选中的样本。样本分布与统计无法代表平台整体,也不自动构成 AI 研究结论。

查看各平台接口积分列表(9个平台、49项接口) ↗

示例:选题与竞品研究

选题与竞品内容研究

确定平台、关键词、样本时间范围和想观察的指标。

示例任务
先查询与“露营收纳”相关的内容,展示本批次返回的样本。保存我选中的结果,按可用指标整理统计;继续翻页前先确认费用。

操作路径

社媒洞察中选平台与操作,查询后检查结果,按需继续获取下一页并保存样本。

产出与费用

每次查询按接口固定积分计费;可对选定样本发起统计分析,分析费用单独查看报价。

样本不代表全站;不要用不同平台不可比的指标直接得出排名结论。

各平台接口积分列表

共9个平台、49项查询接口。下表为2026-11-17发布价格,单位为 xPosts 积分/次,每次查询一页。调价后以提交前的服务端报价为准。

所有接口统一通过 POST /v1/quotes 报价、POST /v1/tasks 提交;使用下表完整能力 ID 作为 capability_id,通过能力详情获取当前 capability_version。输入字段放入 input,具体格式以各接口的 input_schema 为准。

抖音

查询接口能力 ID主要输入积分/次
搜索作品social.douyin.keywordtarget:关键词95
搜索博主social.douyin.creator_searchtarget:关键词10
作品详情social.douyin.contenttarget:作品标识或支持的链接10
博主资料social.douyin.creatortarget:账号标识或支持的链接10
博主作品social.douyin.creator_workstarget:账号标识或支持的链接10
一级评论social.douyin.commentstarget:作品标识或支持的链接10
评论回复social.douyin.comment_repliestarget:作品标识;comment_id:评论 ID10

TikTok

查询接口能力 ID主要输入积分/次
搜索作品social.tiktok.keywordtarget:关键词10
作品详情social.tiktok.contenttarget:作品标识或支持的链接10
博主资料social.tiktok.creatortarget:账号标识或支持的链接10
博主作品social.tiktok.creator_workstarget:账号标识或支持的链接10
一级评论social.tiktok.commentstarget:作品标识或支持的链接10
评论回复social.tiktok.comment_repliestarget:作品标识;comment_id:评论 ID10

YouTube

查询接口能力 ID主要输入积分/次
搜索作品social.youtube.keywordtarget:关键词19
搜索博主social.youtube.creator_searchtarget:关键词19
作品详情social.youtube.contenttarget:作品标识或支持的链接10
博主资料social.youtube.creatortarget:账号标识或支持的链接10
博主作品social.youtube.creator_workstarget:账号标识或支持的链接10
一级评论social.youtube.commentstarget:作品标识或支持的链接10

X

查询接口能力 ID主要输入积分/次
搜索作品social.x.keywordtarget:关键词10
作品详情social.x.contenttarget:作品标识或支持的链接10
博主资料social.x.creatortarget:账号标识或支持的链接10
博主作品social.x.creator_workstarget:账号标识或支持的链接10
一级评论social.x.commentstarget:作品标识或支持的链接10

小红书

查询接口能力 ID主要输入积分/次
搜索作品social.xiaohongshu.keywordtarget:关键词95
作品详情social.xiaohongshu.contenttarget:作品标识或支持的链接95
博主资料social.xiaohongshu.creatortarget:账号标识或支持的链接95
博主作品social.xiaohongshu.creator_workstarget:账号标识或支持的链接95
一级评论social.xiaohongshu.commentstarget:作品标识或支持的链接95

哔哩哔哩

查询接口能力 ID主要输入积分/次
搜索作品social.bilibili.keywordtarget:关键词10
作品详情social.bilibili.contenttarget:作品标识或支持的链接10
博主资料social.bilibili.creatortarget:账号标识或支持的链接10
博主作品social.bilibili.creator_workstarget:账号标识或支持的链接10
一级评论social.bilibili.commentstarget:作品标识或支持的链接10

Instagram

查询接口能力 ID主要输入积分/次
搜索博主social.instagram.creator_searchtarget:关键词19
作品详情social.instagram.contenttarget:作品标识或支持的链接19
博主资料social.instagram.creatortarget:账号标识或支持的链接19
博主作品social.instagram.creator_workstarget:账号标识或支持的链接19
一级评论social.instagram.commentstarget:作品标识或支持的链接19

快手

查询接口能力 ID主要输入积分/次
搜索博主social.kuaishou.creator_searchtarget:关键词95
作品详情social.kuaishou.contenttarget:作品标识或支持的链接10
博主资料social.kuaishou.creatortarget:账号标识或支持的链接95
博主作品social.kuaishou.creator_workstarget:账号标识或支持的链接95
一级评论social.kuaishou.commentstarget:作品标识或支持的链接10

微信公众号

查询接口能力 ID主要输入积分/次
搜索博主social.wechat.creator_searchtarget:关键词95
作品详情social.wechat.contenttarget:作品标识或支持的链接95
博主资料social.wechat.creatortarget:账号标识或支持的链接95
博主作品social.wechat.creator_workstarget:账号标识或支持的链接95
一级评论social.wechat.commentstarget:作品标识或支持的链接95

社媒助手:常用查询接口

所有查询通过 POST /v1/quotes 报价、POST /v1/tasks 提交,再通过 GET /v1/tasks/{id} 读取结果。调用时使用 xPosts API 密钥,无需其他服务的账号或密钥。

先请求 GET /v1/capabilities?kind=social.query&limit=100,按返回的游标读取后续目录;只选择当前可用能力。以下为已实现操作索引,不代表所有部署均已启用。版本与字段约束以能力详情为准。

操作能力 ID 后缀input 输入支持平台
搜索作品keywordtarget:关键词抖音、TikTok、YouTube、X、小红书、哔哩哔哩
搜索博主creator_searchtarget:关键词抖音、YouTube、Instagram、快手、微信
作品详情contenttarget:作品 ID 或支持的链接上述九个平台
博主资料creatortarget:博主 ID 或支持的链接上述九个平台
博主作品creator_workstarget:博主 ID 或支持的链接上述九个平台
一级评论commentstarget:作品 ID 或支持的链接上述九个平台
评论回复comment_repliestarget:作品;comment_id:一级评论 ID抖音、TikTok

能力 ID 格式为 social.{平台}.{后缀}。平台标识依次为 douyin、tiktok、youtube、x、xiaohongshu、bilibili、instagram、kuaishou、wechat。各平台 ID、链接格式和筛选能力不同,不要跨平台复用参数。

target 的平台格式

关键词搜索最多120个字符;其他目标最多2048个字符。请提供下列完整标识或标准链接,不直接粘贴含说明文字的分享文案或短链接。下列链接形式中的标识需替换为实际值。

平台博主资料/作品列表作品详情/评论
抖音MS4wLj 开头的用户标识;www.douyin.com/user/…数字作品ID;www.douyin.com/video/…
TikTok用户名或 @用户名;www.tiktok.com/@…数字视频ID;www.tiktok.com/@用户名/video/…
YouTubeUC开头的频道ID或 /channel/ 频道链接,不支持 @handle 代替频道ID11位视频ID,或 watch、shorts、live、youtu.be 标准视频链接
X用户名、@用户名或 x.com 用户主页数字推文ID或 x.com/用户名/status/… 链接
小红书24位用户ID或 www.xiaohongshu.com/user/profile/…24位笔记ID或 /explore/、/discovery/item/ 笔记链接
哔哩哔哩数字UID或 space.bilibili.com/…BV号或 www.bilibili.com/video/BV…
Instagram用户名、@用户名或 www.instagram.com 用户主页帖子短码或 /p/、/reel/、/reels/、/tv/ 标准链接
快手用户ID或 www.kuaishou.com/profile/…;博主作品查询必须使用数字用户ID作品ID或 www.kuaishou.com/short-video/…
微信公众号gh_开头的公众号原始ID,不是公众号名称完整 mp.weixin.qq.com/s/… 或包含文章参数的 /s?… 链接,不接受裸文章ID

查询数量与平台筛选参数

仅 TikTok 作品搜索、哔哩哔哩作品搜索、抖音博主作品支持 input.limit,可选10或20,默认20。其他操作不要发送该字段。数量是请求的批次大小,实际返回可能更少;计费按查询次数,不按结果条数。

仅抖音作品搜索支持 sort_type 与 publish_time。首批与续页必须保持原参数;并非所有平台都支持按发布时间或点赞排序。

示例:搜索抖音作品

将快速开始中的 CAPABILITY_ID 设置为 social.douyin.keyword,读取详情中的当前版本作为 CAPABILITY_VERSION,将以下示例保存为 input.json,然后执行前述报价、确认提交和任务查询步骤。

查看代码示例
{"target":"咖啡","sort_type":"0","publish_time":"7"}

sort_type:0 综合、1 最多点赞、2 最新发布;publish_time:0 不限、1 最近一天、7 最近一周、180 最近半年。两项均为字符串,默认 0;仅在当前能力版本声明支持时传入。

结果与续页

受理响应不是查询结果。任务成功后读取 result,字段说明见能力的输出结构及 OpenAPI 中的 QueryResult。指标缺失不等于零,查询结果不代表全平台完整数据。

支持续页的操作在下一次输入中保留原 target、筛选和能力版本,并加入 source_task_id 指向原任务;评论回复同时保留 comment_id。续页必须重新报价、确认费用和提交,是独立计费查询。目录或任务列表的 cursor 不能当作社媒续页参数使用。

续页来源必须是同一能力版本和同一查询条件下已成功的上一页任务,且有可用续页结果。续页有效窗口为上一页任务更新后的30分钟;无续页、过期或条件不匹配返回 409 invalid_social_cursor,请重新查询首批。不要把 next_source_cursor 直接作为 input 字段提交。

result 字段说明
result_kindcontent、creator 或 comment,分别对应作品、博主和评论。
items本页结果;成功返回空数组表示本次无结果,不代表请求失败。
metric_definitions各指标含义;缺失指标为 null,不能当作0。
completeness、warningscomplete/partial 及数据不完整原因;不代表覆盖全平台数据。
next_source_cursor、stop_reason续页是否存在及本页停止原因;通过原任务ID续页。

报价和提交需要 tasks:create,读取任务需要 tasks:read。不要在网络超时后换新幂等键盲目重发;先按原请求恢复,避免创建第二个计费任务。

样本统计分析

使用 social.analyze 能力,先读取当前版本和报价,再按相同任务流程提交。输入 source_task_ids 为1–20个有权访问且已成功的查询任务ID,result_kind 为 content、creator 或 comment,group_by 为 platform 或 platform_day。各来源必须为同一结果类型;一次最多10,000条原始样本。同一平台的来源指标口径不同,需要分开分析。

仅分析单个来源任务的部分结果时,可传 source_item_indexes:1–100个不重复的非负索引,从0开始。按日统计使用UTC;去重规则为同平台同来源ID保留最新查询记录。分析单独报价,不包含在查询积分中。

买什么套餐?积分怎么扣?

月卡适合先试运行自己的创作节奏,季卡和年卡适合较稳定的用量;有效订阅期间临时增加任务,可购买永久积分加油包。先估算任务量,再选择钱包中合适的档位。

图片和视频按模型、参数与当前计费设置报价,社媒按具体接口固定积分计费。查询翻页会发起新的任务;样本分析及其他操作按各自报价。图片、视频和查询共用余额,不是分别赠送三套数量。

  1. 选择月卡、季卡或年卡周期分别为 30、90、365 天,积分在对应周期开始时一次发放,套餐积分到期不结转。
  2. 微信扫码,主动付款在钱包核对订单金额、积分与生效时间,扫描付款码。当前为普通支付,不自动续费。
  3. 核对订单与积分付款后以订单状态和生效周期为准。余额异常时先检查订单,不重复付款;保留订单号提交反馈。
  4. 提交时预留,结束后结算确认失败或取消后释放相应预留;状态未知时先查原任务。退款资格和金额以订单退款预览为准。

比较全部套餐和加油包 ↗ · 打开钱包 ↗

查看各平台接口积分列表(9个平台、49项接口) ↗

积分估算、报价与扣减

所有调用均先获取报价,再确认提交。max_units 是本次任务最多预留的 xPosts 积分;参数或报价版本变化后,需要重新报价。

图片与视频

图片费用根据模型、分辨率、质量、张数及参考素材等参数计算;视频费用根据模型、分辨率、生成时长、音频及参考视频等参数计算。可用参数和规格见所选能力的 input_schema。

使用 POST /v1/quotes 获取本次参数对应的积分报价。任务总积分向上取整,实际扣减不超过已确认的报价上限。已受理任务保留原报价;未提交报价失效时,重新获取报价并确认。

社媒查询

社媒按具体查询接口收取固定积分,详见下方各平台接口积分列表。每次查询一页,续页作为新任务另行报价和计费。

冻结与结算

报价本身不扣积分。任务受理时按 max_units 冻结额度;成功后结算并释放未使用部分,明确失败或确认取消后释放。上游结果未知时保留冻结并等待核对,不代表已经退款。释放的原批次若已过期,不恢复为可用积分。

实际扣减不得超过已确认报价上限,不能静默补扣或形成负余额。相同幂等键和相同输入返回原任务,不重复冻结;换新键重新提交可能产生独立任务和费用。余额不足返回 402,任务不会创建。用 GET /v1/usage 查看凭据授权范围内的用量,网页钱包展示当前个人空间余额。

选择你的套餐

以下为当前套餐说明;实际可购买商品、价格、积分与生效时间以钱包下单页为准。

月卡 · 30 天

本周期积分一次发放,未使用积分于周期结束时到期。

入门

偶尔创作,按需查询

¥29 / 月卡

11,000 积分

  • 图片与视频按参数报价
  • 社媒按接口固定积分
  • 实际用量以任务报价为准
去钱包选择 ↗

专业

高频创作,多轮迭代

¥198 / 月卡

110,000 积分

  • 图片与视频按参数报价
  • 社媒按接口固定积分
  • 实际用量以任务报价为准
去钱包选择 ↗

工作室

较大用量,集中制作

¥688 / 月卡

430,000 积分

  • 图片与视频按参数报价
  • 社媒按接口固定积分
  • 实际用量以任务报价为准
去钱包选择 ↗

季卡 · 90 天

本周期积分一次发放,未使用积分于周期结束时到期。

入门

偶尔创作,按需查询

¥78 / 季卡

30,000 积分

  • 图片与视频按参数报价
  • 社媒按接口固定积分
  • 实际用量以任务报价为准
去钱包选择 ↗

专业

高频创作,多轮迭代

¥548 / 季卡

330,000 积分

  • 图片与视频按参数报价
  • 社媒按接口固定积分
  • 实际用量以任务报价为准
去钱包选择 ↗

工作室

较大用量,集中制作

¥1,888 / 季卡

1,200,000 积分

  • 图片与视频按参数报价
  • 社媒按接口固定积分
  • 实际用量以任务报价为准
去钱包选择 ↗

年卡 · 365 天

本周期积分一次发放,未使用积分于周期结束时到期。

入门

偶尔创作,按需查询

¥288 / 年卡

120,000 积分

  • 图片与视频按参数报价
  • 社媒按接口固定积分
  • 实际用量以任务报价为准
去钱包选择 ↗

专业

高频创作,多轮迭代

¥1,998 / 年卡

1,300,000 积分

  • 图片与视频按参数报价
  • 社媒按接口固定积分
  • 实际用量以任务报价为准
去钱包选择 ↗

工作室

较大用量,集中制作

¥6,888 / 年卡

4,520,000 积分

  • 图片与视频按参数报价
  • 社媒按接口固定积分
  • 实际用量以任务报价为准
去钱包选择 ↗

临时多做一些?补充加油包

有效订阅期间可购买。加油包积分永久有效,不延长套餐周期,也不替代使用能力所需的订阅权益。

16k 加油包

永久积分 · 一次购买

¥49 / 包

16,000 积分

  • 图片与视频按参数报价
  • 社媒按接口固定积分
  • 实际用量以任务报价为准
去钱包选择 ↗

42k 加油包

永久积分 · 一次购买

¥99 / 包

42,000 积分

  • 图片与视频按参数报价
  • 社媒按接口固定积分
  • 实际用量以任务报价为准
去钱包选择 ↗

90k 加油包

永久积分 · 一次购买

¥198 / 包

90,000 积分

  • 图片与视频按参数报价
  • 社媒按接口固定积分
  • 实际用量以任务报价为准
去钱包选择 ↗

360k 加油包

永久积分 · 一次购买

¥688 / 包

360,000 积分

  • 图片与视频按参数报价
  • 社媒按接口固定积分
  • 实际用量以任务报价为准
去钱包选择 ↗

混合使用,怎么计算

以入门月卡的 11,000 积分为例

例如,100 次 TikTok 作品详情查询 × 10 积分 + 20 次小红书作品详情查询 × 95 积分 = 2,900 积分,剩余 8,100 积分可继续用于查询或创作。

示例按当前社媒接口费率计算,不包含图片或视频生成。生成任务先获取参数报价,再从同一余额中预留和结算。查看全部接口积分 ↗

任务状态与费用处理

你看到的情况应该怎么做
排队或执行中等待状态更新;可以离开页面,稍后回到任务记录。
成功查看输出并下载;媒体任务和社媒任务的结果形式不同。
失败或已取消检查原因;确认失败或取消后释放相应预留积分,再决定是否重新提交。
结果未知或状态未确认查询原任务并等待核对,不直接当作失败反复创建任务。
浏览器请求超时先核对任务记录。API 调用方复用原幂等键与原请求,避免重复收费。

当前仅排队中的任务可取消;正在执行的任务不支持取消,请继续查询原任务。积分释放回原批次,若原批次已到期,则计入过期积分,不恢复为可用余额。

选适合你的接入方式

方式适合谁如何授权首次验证
网页希望直接操作创作与查询的人登录 xPosts 账号进入个人空间并查看可用能力
Skill能安装 Skill 和运行 Python 的智能体在浏览器批准设备短码执行 status 并读取目录
MCP支持远程 Streamable HTTP 的客户端用当前环境的 OAuth 授权调用 capabilities_list
API自有应用、服务端脚本与批处理服务端发送 Bearer 密钥调用 GET /v1/capabilities
示例:智能体创作流程

把创作接进智能体或应用

先为客户端安装 Skill、配置 MCP,或为自有服务创建最小权限 API 密钥。

示例任务
查看当前图片能力,帮我整理输入条件并展示报价;我确认后再提交,保存任务编号,完成后取回下载地址。

操作路径

先查能力目录,再报价、确认、提交、轮询或接收已配置的回调,最后获取结果。

产出与费用

程序入口与网页共享积分和资源;支持 WorkBuddy 等具备相应集成能力的工作流。

客户端兼容前提与服务配置见接入指南;不要让智能体在未确认费用时循环重试。

六类 AI 助手接入方式

WorkBuddy、千问办公、豆包办公、Codex、DeepSeek 与 Claude Code 可按下面的路径集成。客户端版本需要支持对应扩展能力;此处列出接入路径,不代表六款客户端的所有版本都已完成原生兼容验证。

WorkBuddy

Skill / 本地工具

在可安装自定义 Skill 并执行本地 Python 的版本中,下载官方 Skill,按客户端的 Skill 安装方式加载 xposts 目录,再让智能体执行设备授权。

查看配置步骤 ↗

千问办公

Skill / 应用集成

先确认所用版本允许安装自定义 Skill 或调用外部工具。具备本地执行能力时使用官方 Skill;仅提供对话功能的版本不能直接执行创作任务。

查看配置步骤 ↗

豆包办公

Skill / 应用集成

在支持自定义工具或 Skill 的工作环境中连接。若版本没有扩展入口,可由开发者通过 API 集成;不需要把 xPosts 密钥粘贴进普通聊天。

查看配置步骤 ↗

Codex

Skill / CLI

将官方 xposts Skill 安装到 Codex 可发现的技能目录,确保可以运行 Python。让 Codex 读取 SKILL.md,执行 login 并在浏览器核对授权。

查看配置步骤 ↗

DeepSeek

API / 自有应用

由使用 DeepSeek 的应用在服务端调用 xPosts API,并将能力查询、报价和任务结果交给模型处理。模型提供建议,应用执行工具;普通聊天页不等于已安装 xPosts。

查看配置步骤 ↗

Claude Code

Skill / CLI

在 Claude Code 可发现的 Skill 目录加载官方包,保留脚本并检查 Python。先读取技能说明完成授权,再调用能力目录;MCP 可作为环境配置完备时的另一条路径。

查看配置步骤 ↗

Skill 安装与设备授权

适合能读取 SKILL.md 并运行本地 Python 命令的智能体。当前发布版本为 0.1.7,需要 Python 3.10 或更新版本。

  1. 通过当前站点下载 ZIP,解压后按客户端说明安装包含 SKILL.md 的 xposts 目录。保留 scripts 目录。
  2. 在终端进入解压后的 xposts 目录,将 XPOSTS_ORIGIN 设为工作台的协议、主机与端口。
  3. 执行 login,打开终端返回的授权地址,核对短码、客户端、权限及资源范围后批准。终端会等待授权结果。只读使用时可以省略 --scope,使用默认只读权限。
查看代码示例
python scripts/xposts.py --base-url "$XPOSTS_ORIGIN" login --scope "capabilities:read tasks:read tasks:create assets:read assets:write usage:read"
python scripts/xposts.py --base-url "$XPOSTS_ORIGIN" status
python scripts/xposts.py --base-url "$XPOSTS_ORIGIN" capabilities --kind social.query --platform douyin

使用 capability ID 查输入结构。确认后可用 quote、submit --idempotency-key、task get 和 download。先读包内 README 的命令格式,再提交会预留额度的任务。设备授权失败时检查短码是否过期、浏览器是否登录了要连接的空间,以及终端与浏览器是否使用同一环境。

下载包 SHA-256 4d1dd496e3069a906d68d592a46867d41aa23c99718b7f8cded075a13ba159b5。断开时执行 logout。远端撤销结果未确认时,回到工作台的已授权连接手动撤销。

授权后怎么确认可以使用

先让终端完成授权并成功执行 status,再查一次能力目录。首个任务可以让智能体为你挑选当前可用的图片模型、显示报价,等你确认后提交一张图。保留任务编号,成功后在工作台「素材与作品」核对产出。

接入 MCP 客户端

需要支持远程 Streamable HTTP 和 OAuth 的客户端。打开「连接智能体 → MCP 接入」,复制该环境展示的资源地址及发现配置。显示 MCP 未配置时,该环境暂时无法授权连接。

  1. 将资源地址作为远程 MCP 服务添加到客户端。
  2. 由客户端按服务发现进入浏览器授权。核对 scope、空间以及是否允许提交收费任务。
  3. 授权后先调用 capabilities_list 检查连接。读取某项能力用 capabilities_get,确认费用后再调用 quotes_create 和 tasks_create。
  4. 通过 tasks_get 查询状态。媒体结果使用 assets_download 获取短期地址,社媒结果读取任务结构化输出。

401 通常需要检查登录、资源地址或授权状态。403 检查所授 scope。大文件先通过素材工具获得受限上传地址,再传送文件。工具及参数见 工具清单。

打开 MCP 接入 ↗

账号、连接与最小权限

网页、Skill、MCP 和 API 共享相应空间内的资源与积分,但每项操作仍需通过授权检查。不要把 API 密钥放在网页代码、公开仓库或聊天截图里。

为不同应用创建独立连接,只授予必要权限;不再使用时从连接管理撤销。权限不足应重新授权,不通过传入其他空间或用户标识绕过限制。

连接管理与费用权限

管理连接与费用权限

从工作台可以查看已授权连接、密钥和最近使用记录。各入口共享空间余额。分开为不同应用授权、视需要撤销或轮换密钥。程序入口只能使用现有权益,购买套餐或额度包请从工作台处理。

阅读定价与额度规则 ↗

DEVELOPERS / API 文档

开发者 API 文档

以程序方式调用 xPosts 的图片、视频、社媒查询、样本分析及提示词能力。先读取能力目录和报价,提交后用任务编号跟踪结果。

地址、密钥与权限

API 使用与已登录工作台相同的服务地址,业务路由以 /v1 开头。进入「开发者中心 → API 密钥」创建密钥,选择最小权限和到期时间。服务端明文只返回一次,请用服务端环境变量保存。

每次请求发送 Authorization: Bearer $XPOSTS_API_KEY。JSON 写请求发送 Content-Type: application/json。own 仅访问该凭据可见的自有资源,workspace 可访问明确授权的同一空间资源。空间由服务端从身份确定,请求体无需提供空间 ID。

下面的命令使用 Bash、curl、jq 和 Python 3。将 XPOSTS_ORIGIN 设置为工作台的协议、主机与端口,并通过环境变量提供 API 密钥。

快速开始

1. 查目录并选择能力

查看代码示例
curl -fsS "$XPOSTS_ORIGIN/v1/capabilities?kind=image.generate&limit=20" \
  -H "Authorization: Bearer $XPOSTS_API_KEY"

从可用项取 id,再读取 GET /v1/capabilities/{id} 的 version 和 input_schema。把选定的 ID 和版本分别放入 CAPABILITY_ID、CAPABILITY_VERSION。按目录结构编写 input.json,例如图片输入包含提示词及该模型要求的尺寸或比例。社媒操作按目录要求提供关键词、URL 或账号标识。

如果所选图片模型只要求提示词,input.json 可以写成:

查看代码示例
{"prompt":"为周末市集创作一张清晨调色的海报"}

2. 获取报价

查看代码示例
jq -n --arg id "$CAPABILITY_ID" --arg version "$CAPABILITY_VERSION" \
  --slurpfile inputs input.json \
  '{capability_id:$id, capability_version:$version, input:$inputs[0]}' > quote-request.json
curl -fsS "$XPOSTS_ORIGIN/v1/quotes" \
  -H "Authorization: Bearer $XPOSTS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @quote-request.json > quote.json
jq '{id, max_units, unit, expires_at}' quote.json

报价响应与有效期

成功返回 201。响应字段:id 为报价编号,unit 为积分单位,max_units 为最多预留积分,price_version 为费率版本,expires_at 为过期时间。正式积分单位为 credit;测试环境可能返回 test_credit,两者不能混用。

报价有效期为5分钟,以 expires_at 为准。报价绑定能力版本、输入及调用身份,且只能用于一次新任务;不能修改输入后继续使用同一报价。过期、已使用或输入不一致返回 409 quote_invalid,需重新报价。调价也可能使未提交报价失效。

3. 确认费用后提交

提交需要有效订阅及足够可用积分,会按报价上限预留额度。client_request_id 使用 UUID,Idempotency-Key 为16–128个可打印 ASCII 字符。将下面第一段只运行一次,保留生成的 ID 和请求文件。网络中断时复用原文件与原幂等键。

查看代码示例
REQUEST_ID=$(python3 -c 'import uuid; print(uuid.uuid4())')
printf '%s\n' "$REQUEST_ID" > request-id.txt
jq --arg request "$REQUEST_ID" --slurpfile quote quote.json \
  '. + {quote_id:$quote[0].id, client_request_id:$request}' quote-request.json > task-request.json

curl -fsS "$XPOSTS_ORIGIN/v1/tasks" \
  -H "Authorization: Bearer $XPOSTS_API_KEY" \
  -H "Idempotency-Key: $(cat request-id.txt)" \
  -H 'Content-Type: application/json' \
  --data-binary @task-request.json > task.json
jq '{id, state}' task.json

4. 查任务及结果

查看代码示例
TASK_ID=$(jq -r .id task.json)
curl -fsS "$XPOSTS_ORIGIN/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $XPOSTS_API_KEY"

202 表示任务受理。查看 state、stage 和 billing_state。成功后,图片和视频从 output_asset_ids 下载,社媒查询和分析读取 result。看到待核对状态时继续观察原编号。

图片与视频输入示例

先从能力目录选择对应模型,获取其当前 ID、版本与输入结构。以下仅为 input.json 的示例内容,不能跨模型混用;按快速开始流程报价后提交。

GPT Image 2:文字生成图片

查看代码示例
{"prompt":"柔和晨光下的一杯咖啡,简洁背景","resolution":"1k","aspect_ratio":"1:1","quality":"medium","count":1,"output_format":"png"}

Grok Imagine Video 1.5:文字生成视频

查看代码示例
{"prompt":"咖啡杯特写,蒸汽缓慢升起,镜头轻轻推进","seconds":5,"resolution":"480p","aspect_ratio":"16:9","generate_audio":false}

Seedance 2 Mini:使用参考素材

将示例 UUID 替换为当前凭据可访问且已就绪的参考图片编号。参考视频也通过 asset_ids 提供,并额外填写 person_reference。该字段只在使用参考视频时用于声明是否含真实人物。

查看代码示例
{"prompt":"保持参考主体,镜头缓慢平移","asset_ids":["00000000-0000-4000-8000-000000000001"],"seconds":4,"resolution":"480p","aspect_ratio":"16:9","generate_audio":false}

当前图片提示词最多8,000字符,视频最多2,000字符。参考素材须先完成上传及校验,不能把本机路径或任意图片网址放入 asset_ids。

接口与权限索引

完整请求字段、参数、状态码和响应结构见 OpenAPI 契约。模型与社媒平台的当前结构以能力目录为准。

展开全部接口与所需权限
方法路径所需权限
GET/v1/capabilitiescapabilities:read
GET/v1/capabilities/{id}capabilities:read
POST/v1/quotestasks:create
POST/v1/taskstasks:create
GET/v1/taskstasks:read
GET/v1/tasks/{id}tasks:read
POST/v1/tasks/{id}/canceltasks:cancel
POST/v1/assets/uploadsassets:write
POST/v1/assets/{id}/completeassets:write
GET/v1/assetsassets:read
GET/v1/assets/{id}assets:read
DELETE/v1/assets/{id}assets:delete
GET/v1/assets/{id}/downloadassets:read
GET/v1/usageusage:read
GET/v1/webhookswebhooks:write
POST/v1/webhookswebhooks:write
DELETE/v1/webhooks/{id}webhooks:write
GET/v1/webhooks/{id}/deliverieswebhooks:write
POST/v1/webhooks/{id}/rotate-keywebhooks:write
POST/v1/webhooks/{id}/testwebhooks:write
POST/v1/webhooks/{id}/replaywebhooks:write
GET/v1/prompt-reviewtasks:create
POST/v1/prompt-reviewtasks:create
POST/v1/prompt-review/assetstasks:create
DELETE/v1/credentials/selfself

任务状态、结果与取消

提交成功返回202及任务摘要,完整结果通过 GET /v1/tasks/{id} 获取。state 表示任务状态,stage 表示执行阶段;请分别读取,不把阶段值当作任务状态。

state含义与处理
queued排队中,可继续查询或取消。
running执行中,继续查询原任务,当前不支持取消。
succeeded成功。媒体读取 output_asset_ids,社媒查询与分析读取 result。
failed失败。查看错误原因及 billing_state,再决定是否重新创建任务。
canceled已取消。核对积分释放状态。

billing_state:reserved 为已预留、settled 为已结算、released 为已释放、reconciliation 为待核对。reconcile_state=pending 表示仍需核对,不能自行认定成功或已退款。

取消使用 POST /v1/tasks/{id}/cancel,需要 tasks:cancel。执行中的任务返回 409 cancel_not_supported,不要以取消请求代替最终状态检查。

轮询建议间隔数秒,并在连续等待时逐步延长;收到429时遵循响应的重试提示。查询历史任务可用 GET /v1/tasks?limit=20&state=succeeded&kind=social.query,按 next_cursor 续读。

私有素材、社媒分页与提示词

素材格式、大小、参考图数量、蒙版及参考视频限制见素材限制表。API引用素材使用 input.asset_ids;图片蒙版的 mask_asset_id 必须同时存在于该数组中,且与数组中第一张非蒙版原图尺寸一致。使用参考视频时还需明确提供 person_reference 布尔值。

  • 上传。用 POST /v1/assets/uploads 声明文件名、MIME、字节数与 SHA-256,按响应的短期地址和请求头传输原文件,再调 POST /v1/assets/{id}/complete。只引用 ready 的素材。传输到签名地址时使用响应指定的请求头。
  • 下载。用 GET /v1/assets/{id}/download 取得短期签名地址。地址过期后重新申请,请勿公开分享。生成引用的限制以当前能力版本为准。
  • 列表与社媒续页。列表用 next_cursor 作为下一次请求的 cursor,沿用原筛选,直到游标为空。支持续页的社媒操作使用原任务作为 source_task_id,保持同一版能力、目标与筛选后另行报价和确认。
  • 提示词检查和反推。GET /v1/prompt-review 检查可用性,POST /v1/prompt-review 可提交文本或约定格式的 JPEG 预览,POST /v1/prompt-review/assets 可使用已就绪的 JPEG 素材。发送前由用户确认。有图像、关键帧或遮罩时按 OpenAPI 提供对应字段,复用私有素材还需 assets:read。

Webhook 回调

先在开发者中心确认当前环境已启用 Webhook 投递。未启用时通过任务查询获取状态,不依赖回调完成业务流程。

创建 HTTPS 端点后,将 webhook_endpoint_id 放进任务请求。接收成功、失败和取消事件时,对原始正文校验 HMAC-SHA256。签名输入是 timestamp + "." + 原始正文,密钥为端点签名密钥。读取 X-XPosts-Timestamp、X-XPosts-Signature、X-XPosts-Event-Id、X-XPosts-Delivery-Id,验证时间窗口并按事件 ID 去重。投递测试、重放和密钥轮换见接口索引。

请求超时、排队与重试

  1. 已拿到任务编号。继续查询原任务。queued 或 running 表示任务已受理,stage 为 finalizing 时仍需等待作品保存和结算。
  2. 提交后连接断开,尚未拿到任务编号。先检查同一凭据可见的近期任务。重试时沿用原请求体、client_request_id 和 Idempotency-Key。同一任务已经受理时会返回原编号。
  3. 确定未受理,且报价或参数已变化。读取当前目录,重新报价并确认,再用新的请求编号和幂等键提交。

错误响应字段位于 error 对象中,包括 error.code、error.message、error.retryable 和 error.request_id。记录请求编号用于排查。对可重试错误退避,收到 Retry-After 时按该值等待。创建任务的重试必须沿用原请求体和幂等键。

状态处理
401 / 403 / 404核对凭据、权限、资源归属与可见性。
402检查订阅状态或可用额度,再决定是否继续。
409 idempotency_conflict同一键对应了不同请求。恢复原请求核对其状态。确实要发起另一项任务时,重新报价并确认。
410 / 422按 error.code 核对报价、素材状态及输入结构。
429 / 503检查限额或服务状态,按响应指示退避和重试。

遇到问题,从这里检查

无法提交任务

先看必填参数、素材就绪状态、有效订阅与可用积分。模型切换后重新检查条件与报价。

签名下载链接打不开

临时链接可能已经到期。回到作品重新获取;仍失败时记录素材或任务编号并提交反馈。

智能体已安装,但无法调用

先执行连接状态检查,再读取能力目录;核对服务地址、授权账号与 scope。MCP 还需要当前环境启用 OAuth。

如何反馈问题?

在工作台设置中提交反馈,附上任务或订单编号、发生时间和错误提示。不要附带密码、密钥或完整授权链接。

提交反馈 ↗ · 开发者重试与恢复指南 ↗

购买前常见问题

月卡、季卡和年卡会自动续费吗?

不会。当前采用微信普通支付,每次由你主动下单并付款。

年卡积分按月发放吗?

不是。积分在年卡周期开始时一次发放,365 天周期结束时到期;季卡为 90 天、月卡为 30 天。

为什么生成时可用余额会减少?

提交任务会先预留报价对应的积分。确认失败或取消后释放预留;状态未知时先查询原任务。

我可以只买加油包吗?

加油包用于有效订阅期间补充积分,不能代替套餐。购买前钱包会检查当前权益。

付款成功但余额没有变化怎么办?

先刷新订单状态,确认订单对应的生效周期;仍有异常时保留订单号提交反馈,不要反复付款。

使用前,了解这些边界

网站上展示的模型是否一直可用?

模型与规格可能随供应方和服务配置调整。工作台当前能力目录、输入校验及提交前报价是使用依据。

可以自动发布或获取私密账号内容吗?

当前提供创作、查询与样本分析,不提供自动发布、私信触达或绕过平台权限获取私密内容的能力。

任务失败会如何处理积分?

确认失败或取消后释放相应预留积分;状态未知或仍等待供应方确认时,先保留预留并继续核对。

所有智能体都能直接安装吗?

客户端需要具备相应 Skill、MCP 或应用集成能力。接入指南会分别说明六类常用入口的前提,不同版本的菜单和支持程度可能不同。

接入遇到问题

设备授权仍在等待
打开终端返回的授权页,核对短码和账号后批准。access_denied 或 expired_token 时再次运行 login 获取新短码。
MCP 显示未配置或没有出现工具
从工作台复制当前环境给出的资源地址。确认客户端支持远程 Streamable HTTP 和 OAuth,授权后用 tools/list 核对当前实际提供的工具。
连接成功,但操作被拒绝
先核对该操作要求的 scope 及资源范围。需要增加权限时,使用相应入口重新授权。权限正确但返回 402 时,再检查订阅和可用额度。

查看请求超时与重试方法 ↗