快速开始 ↗
登录、确认积分并完成首个任务
从首次创作到程序接入,在一页找到操作步骤、接口参数与积分规则。
| 你的目标 | 准备什么 | 如何做与得到什么 |
|---|---|---|
| 电商商品图、活动封面 | 商品图、品牌色、用途和画面比例 | 图片创作,得到可检查和下载的视觉素材 |
| 社媒选题、竞品内容研究 | 平台、关键词或公开内容 / 账号链接 | 查询并保存样本,查看内容、创作者、评论等可用字段及统计 |
| 借鉴热门视频的表达方式 | 有权使用的参考视频、自己的主体与素材 | 关键帧分析与提示词反推,再生成自己的短片 |
| 商品动态展示、创意镜头 | 一个主体、动作与镜头方向,必要的参考素材 | 视频生成,得到 4–5 秒无音频短片素材 |
| 在 AI 助手里持续创作 | 支持扩展的客户端、xPosts 账号与相应权益 | 连接客户端,由助手调用并追踪同一工作台的任务 |
准备:已登录账号、有效订阅、足以覆盖本次报价的可用积分。使用参考图时,先确保素材已经上传并通过校验。
当前图片模型为 GPT Image 2。适合商品展示、社媒封面、场景概念与视觉方案;生成内容仍需由你检查文字、细节与使用权。
| 条件 | 当前支持 |
|---|---|
| 输出 | 1K,每任务 1 张 |
| 画面比例 | 1:1、16:9、9:16、4:3 |
| 质量 | low、medium、high,以工作台可选项为准 |
| 参考素材 | 最多 4 张参考图,可另加 1 张同尺寸 PNG 蒙版 |
| 提示词 | 1–8,000 字符 |
| 费用 | 按模型参数报价,提交前展示报价 |
准备一张可用的商品参考图、品牌色与画面用途。
在创作工作室选择图片模型,上传参考图,选择比例,确认本次积分报价后生成。
获得 1 张 1K 图片,检查商品细节、文字和品牌一致性后使用。
参考素材只能帮助表达方向,不保证逐像素复刻。
准备主题、目标受众、画面比例与希望预留的文字位置。
按发布位置选 9:16 或其他可用比例,先生成一版,再按结果调整提示词。
图片任务按模型与参数报价;多次修改重新生成会分别计费。
最终标题与文字需自行核对,平台不代为发布。
准备:已登录账号、有效订阅及足以覆盖本次报价的可用积分;选择需要参考素材的模型时,先准备有权使用的素材。
不同模型的输入要求不同。当前开放固定短片规格,不能把所有模型的条件混用;不承诺固定完成时间。
| 模型 | 输出规格 | 输入与用途 | 积分 |
|---|---|---|---|
| Grok Imagine Video 1.5 | 480p · 5 秒 · 无音频 | 提示词输入;当前不支持参考图片或视频 | 按模型参数报价 |
| Seedance 2 Mini | 480p · 4 秒 · 16:9 · 无音频 | 必须提供参考素材及提示词;最多3张图片+1段视频,至少1项 | 按模型参数报价 |
提交前检查镜头运动、主体动作和画面比例。素材类型、大小与组合限制以所选模型的表单校验为准。长片剪辑、音乐制作与自动发布不属于当前视频生成范围。
明确一个动作、一个主体与一个镜头变化,避免在数秒内安排过多情节。
选择 Grok Imagine Video 1.5,检查条件和报价,提交后通过任务编号跟踪。
当前规格为 480p、5 秒、无音频,按模型参数报价。
这是短片素材生成;长片剪辑、配乐与自动分发需另行完成。
准备你有权使用的参考素材:最多3张图片+1段视频,至少1项。
选择 Seedance 2 Mini,等待参考素材校验完成,再填写提示词并核对输出规格。
当前规格为 16:9、480p、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 字节。素材库上传上限与生成参考上限不同;通过上传校验不代表适用于所有模型。
确定平台、关键词、样本时间范围和想观察的指标。
社媒洞察中选平台与操作,查询后检查结果,按需继续获取下一页并保存样本。
每次查询按接口固定积分计费;可对选定样本发起统计分析,分析费用单独查看报价。
样本不代表全站;不要用不同平台不可比的指标直接得出排名结论。
共9个平台、49项查询接口。下表为2026-11-17发布价格,单位为 xPosts 积分/次,每次查询一页。调价后以提交前的服务端报价为准。
所有接口统一通过 POST /v1/quotes 报价、POST /v1/tasks 提交;使用下表完整能力 ID 作为 capability_id,通过能力详情获取当前 capability_version。输入字段放入 input,具体格式以各接口的 input_schema 为准。
| 查询接口 | 能力 ID | 主要输入 | 积分/次 |
|---|---|---|---|
| 搜索作品 | social.douyin.keyword | target:关键词 | 95 |
| 搜索博主 | social.douyin.creator_search | target:关键词 | 10 |
| 作品详情 | social.douyin.content | target:作品标识或支持的链接 | 10 |
| 博主资料 | social.douyin.creator | target:账号标识或支持的链接 | 10 |
| 博主作品 | social.douyin.creator_works | target:账号标识或支持的链接 | 10 |
| 一级评论 | social.douyin.comments | target:作品标识或支持的链接 | 10 |
| 评论回复 | social.douyin.comment_replies | target:作品标识;comment_id:评论 ID | 10 |
| 查询接口 | 能力 ID | 主要输入 | 积分/次 |
|---|---|---|---|
| 搜索作品 | social.tiktok.keyword | target:关键词 | 10 |
| 作品详情 | social.tiktok.content | target:作品标识或支持的链接 | 10 |
| 博主资料 | social.tiktok.creator | target:账号标识或支持的链接 | 10 |
| 博主作品 | social.tiktok.creator_works | target:账号标识或支持的链接 | 10 |
| 一级评论 | social.tiktok.comments | target:作品标识或支持的链接 | 10 |
| 评论回复 | social.tiktok.comment_replies | target:作品标识;comment_id:评论 ID | 10 |
| 查询接口 | 能力 ID | 主要输入 | 积分/次 |
|---|---|---|---|
| 搜索作品 | social.youtube.keyword | target:关键词 | 19 |
| 搜索博主 | social.youtube.creator_search | target:关键词 | 19 |
| 作品详情 | social.youtube.content | target:作品标识或支持的链接 | 10 |
| 博主资料 | social.youtube.creator | target:账号标识或支持的链接 | 10 |
| 博主作品 | social.youtube.creator_works | target:账号标识或支持的链接 | 10 |
| 一级评论 | social.youtube.comments | target:作品标识或支持的链接 | 10 |
| 查询接口 | 能力 ID | 主要输入 | 积分/次 |
|---|---|---|---|
| 搜索作品 | social.x.keyword | target:关键词 | 10 |
| 作品详情 | social.x.content | target:作品标识或支持的链接 | 10 |
| 博主资料 | social.x.creator | target:账号标识或支持的链接 | 10 |
| 博主作品 | social.x.creator_works | target:账号标识或支持的链接 | 10 |
| 一级评论 | social.x.comments | target:作品标识或支持的链接 | 10 |
| 查询接口 | 能力 ID | 主要输入 | 积分/次 |
|---|---|---|---|
| 搜索作品 | social.xiaohongshu.keyword | target:关键词 | 95 |
| 作品详情 | social.xiaohongshu.content | target:作品标识或支持的链接 | 95 |
| 博主资料 | social.xiaohongshu.creator | target:账号标识或支持的链接 | 95 |
| 博主作品 | social.xiaohongshu.creator_works | target:账号标识或支持的链接 | 95 |
| 一级评论 | social.xiaohongshu.comments | target:作品标识或支持的链接 | 95 |
| 查询接口 | 能力 ID | 主要输入 | 积分/次 |
|---|---|---|---|
| 搜索作品 | social.bilibili.keyword | target:关键词 | 10 |
| 作品详情 | social.bilibili.content | target:作品标识或支持的链接 | 10 |
| 博主资料 | social.bilibili.creator | target:账号标识或支持的链接 | 10 |
| 博主作品 | social.bilibili.creator_works | target:账号标识或支持的链接 | 10 |
| 一级评论 | social.bilibili.comments | target:作品标识或支持的链接 | 10 |
| 查询接口 | 能力 ID | 主要输入 | 积分/次 |
|---|---|---|---|
| 搜索博主 | social.instagram.creator_search | target:关键词 | 19 |
| 作品详情 | social.instagram.content | target:作品标识或支持的链接 | 19 |
| 博主资料 | social.instagram.creator | target:账号标识或支持的链接 | 19 |
| 博主作品 | social.instagram.creator_works | target:账号标识或支持的链接 | 19 |
| 一级评论 | social.instagram.comments | target:作品标识或支持的链接 | 19 |
| 查询接口 | 能力 ID | 主要输入 | 积分/次 |
|---|---|---|---|
| 搜索博主 | social.kuaishou.creator_search | target:关键词 | 95 |
| 作品详情 | social.kuaishou.content | target:作品标识或支持的链接 | 10 |
| 博主资料 | social.kuaishou.creator | target:账号标识或支持的链接 | 95 |
| 博主作品 | social.kuaishou.creator_works | target:账号标识或支持的链接 | 95 |
| 一级评论 | social.kuaishou.comments | target:作品标识或支持的链接 | 10 |
| 查询接口 | 能力 ID | 主要输入 | 积分/次 |
|---|---|---|---|
| 搜索博主 | social.wechat.creator_search | target:关键词 | 95 |
| 作品详情 | social.wechat.content | target:作品标识或支持的链接 | 95 |
| 博主资料 | social.wechat.creator | target:账号标识或支持的链接 | 95 |
| 博主作品 | social.wechat.creator_works | target:账号标识或支持的链接 | 95 |
| 一级评论 | social.wechat.comments | target:作品标识或支持的链接 | 95 |
所有查询通过 POST /v1/quotes 报价、POST /v1/tasks 提交,再通过 GET /v1/tasks/{id} 读取结果。调用时使用 xPosts API 密钥,无需其他服务的账号或密钥。
先请求 GET /v1/capabilities?kind=social.query&limit=100,按返回的游标读取后续目录;只选择当前可用能力。以下为已实现操作索引,不代表所有部署均已启用。版本与字段约束以能力详情为准。
| 操作 | 能力 ID 后缀 | input 输入 | 支持平台 |
|---|---|---|---|
| 搜索作品 | keyword | target:关键词 | 抖音、TikTok、YouTube、X、小红书、哔哩哔哩 |
| 搜索博主 | creator_search | target:关键词 | 抖音、YouTube、Instagram、快手、微信 |
| 作品详情 | content | target:作品 ID 或支持的链接 | 上述九个平台 |
| 博主资料 | creator | target:博主 ID 或支持的链接 | 上述九个平台 |
| 博主作品 | creator_works | target:博主 ID 或支持的链接 | 上述九个平台 |
| 一级评论 | comments | target:作品 ID 或支持的链接 | 上述九个平台 |
| 评论回复 | comment_replies | target:作品;comment_id:一级评论 ID | 抖音、TikTok |
能力 ID 格式为 social.{平台}.{后缀}。平台标识依次为 douyin、tiktok、youtube、x、xiaohongshu、bilibili、instagram、kuaishou、wechat。各平台 ID、链接格式和筛选能力不同,不要跨平台复用参数。
关键词搜索最多120个字符;其他目标最多2048个字符。请提供下列完整标识或标准链接,不直接粘贴含说明文字的分享文案或短链接。下列链接形式中的标识需替换为实际值。
| 平台 | 博主资料/作品列表 | 作品详情/评论 |
|---|---|---|
| 抖音 | MS4wLj 开头的用户标识;www.douyin.com/user/… | 数字作品ID;www.douyin.com/video/… |
| TikTok | 用户名或 @用户名;www.tiktok.com/@… | 数字视频ID;www.tiktok.com/@用户名/video/… |
| YouTube | UC开头的频道ID或 /channel/ 频道链接,不支持 @handle 代替频道ID | 11位视频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… |
| 用户名、@用户名或 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_kind | content、creator 或 comment,分别对应作品、博主和评论。 |
| items | 本页结果;成功返回空数组表示本次无结果,不代表请求失败。 |
| metric_definitions | 各指标含义;缺失指标为 null,不能当作0。 |
| completeness、warnings | complete/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保留最新查询记录。分析单独报价,不包含在查询积分中。
月卡适合先试运行自己的创作节奏,季卡和年卡适合较稳定的用量;有效订阅期间临时增加任务,可购买永久积分加油包。先估算任务量,再选择钱包中合适的档位。
图片和视频按模型、参数与当前计费设置报价,社媒按具体接口固定积分计费。查询翻页会发起新的任务;样本分析及其他操作按各自报价。图片、视频和查询共用余额,不是分别赠送三套数量。
所有调用均先获取报价,再确认提交。max_units 是本次任务最多预留的 xPosts 积分;参数或报价版本变化后,需要重新报价。
图片费用根据模型、分辨率、质量、张数及参考素材等参数计算;视频费用根据模型、分辨率、生成时长、音频及参考视频等参数计算。可用参数和规格见所选能力的 input_schema。
使用 POST /v1/quotes 获取本次参数对应的积分报价。任务总积分向上取整,实际扣减不超过已确认的报价上限。已受理任务保留原报价;未提交报价失效时,重新获取报价并确认。
社媒按具体查询接口收取固定积分,详见下方各平台接口积分列表。每次查询一页,续页作为新任务另行报价和计费。
报价本身不扣积分。任务受理时按 max_units 冻结额度;成功后结算并释放未使用部分,明确失败或确认取消后释放。上游结果未知时保留冻结并等待核对,不代表已经退款。释放的原批次若已过期,不恢复为可用积分。
实际扣减不得超过已确认报价上限,不能静默补扣或形成负余额。相同幂等键和相同输入返回原任务,不重复冻结;换新键重新提交可能产生独立任务和费用。余额不足返回 402,任务不会创建。用 GET /v1/usage 查看凭据授权范围内的用量,网页钱包展示当前个人空间余额。
| 你看到的情况 | 应该怎么做 |
|---|---|
| 排队或执行中 | 等待状态更新;可以离开页面,稍后回到任务记录。 |
| 成功 | 查看输出并下载;媒体任务和社媒任务的结果形式不同。 |
| 失败或已取消 | 检查原因;确认失败或取消后释放相应预留积分,再决定是否重新提交。 |
| 结果未知或状态未确认 | 查询原任务并等待核对,不直接当作失败反复创建任务。 |
| 浏览器请求超时 | 先核对任务记录。API 调用方复用原幂等键与原请求,避免重复收费。 |
当前仅排队中的任务可取消;正在执行的任务不支持取消,请继续查询原任务。积分释放回原批次,若原批次已到期,则计入过期积分,不恢复为可用余额。
| 方式 | 适合谁 | 如何授权 | 首次验证 |
|---|---|---|---|
| 网页 | 希望直接操作创作与查询的人 | 登录 xPosts 账号 | 进入个人空间并查看可用能力 |
| Skill | 能安装 Skill 和运行 Python 的智能体 | 在浏览器批准设备短码 | 执行 status 并读取目录 |
| MCP | 支持远程 Streamable HTTP 的客户端 | 用当前环境的 OAuth 授权 | 调用 capabilities_list |
| API | 自有应用、服务端脚本与批处理 | 服务端发送 Bearer 密钥 | 调用 GET /v1/capabilities |
先为客户端安装 Skill、配置 MCP,或为自有服务创建最小权限 API 密钥。
先查能力目录,再报价、确认、提交、轮询或接收已配置的回调,最后获取结果。
程序入口与网页共享积分和资源;支持 WorkBuddy 等具备相应集成能力的工作流。
客户端兼容前提与服务配置见接入指南;不要让智能体在未确认费用时循环重试。
WorkBuddy、千问办公、豆包办公、Codex、DeepSeek 与 Claude Code 可按下面的路径集成。客户端版本需要支持对应扩展能力;此处列出接入路径,不代表六款客户端的所有版本都已完成原生兼容验证。
Skill / 本地工具
在可安装自定义 Skill 并执行本地 Python 的版本中,下载官方 Skill,按客户端的 Skill 安装方式加载 xposts 目录,再让智能体执行设备授权。
查看配置步骤 ↗Skill / 应用集成
先确认所用版本允许安装自定义 Skill 或调用外部工具。具备本地执行能力时使用官方 Skill;仅提供对话功能的版本不能直接执行创作任务。
查看配置步骤 ↗Skill / 应用集成
在支持自定义工具或 Skill 的工作环境中连接。若版本没有扩展入口,可由开发者通过 API 集成;不需要把 xPosts 密钥粘贴进普通聊天。
查看配置步骤 ↗Skill / CLI
将官方 xposts Skill 安装到 Codex 可发现的技能目录,确保可以运行 Python。让 Codex 读取 SKILL.md,执行 login 并在浏览器核对授权。
查看配置步骤 ↗API / 自有应用
由使用 DeepSeek 的应用在服务端调用 xPosts API,并将能力查询、报价和任务结果交给模型处理。模型提供建议,应用执行工具;普通聊天页不等于已安装 xPosts。
查看配置步骤 ↗Skill / CLI
在 Claude Code 可发现的 Skill 目录加载官方包,保留脚本并检查 Python。先读取技能说明完成授权,再调用能力目录;MCP 可作为环境配置完备时的另一条路径。
查看配置步骤 ↗适合能读取 SKILL.md 并运行本地 Python 命令的智能体。当前发布版本为 0.1.7,需要 Python 3.10 或更新版本。
SKILL.md 的 xposts 目录。保留 scripts 目录。xposts 目录,将 XPOSTS_ORIGIN 设为工作台的协议、主机与端口。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,再查一次能力目录。首个任务可以让智能体为你挑选当前可用的图片模型、显示报价,等你确认后提交一张图。保留任务编号,成功后在工作台「素材与作品」核对产出。
需要支持远程 Streamable HTTP 和 OAuth 的客户端。打开「连接智能体 → MCP 接入」,复制该环境展示的资源地址及发现配置。显示 MCP 未配置时,该环境暂时无法授权连接。
capabilities_list 检查连接。读取某项能力用 capabilities_get,确认费用后再调用 quotes_create 和 tasks_create。tasks_get 查询状态。媒体结果使用 assets_download 获取短期地址,社媒结果读取任务结构化输出。401 通常需要检查登录、资源地址或授权状态。403 检查所授 scope。大文件先通过素材工具获得受限上传地址,再传送文件。工具及参数见 工具清单。
网页、Skill、MCP 和 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 密钥。
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":"为周末市集创作一张清晨调色的海报"}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,需重新报价。调价也可能使未提交报价失效。
提交需要有效订阅及足够可用积分,会按报价上限预留额度。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.jsonTASK_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 的示例内容,不能跨模型混用;按快速开始流程报价后提交。
{"prompt":"柔和晨光下的一杯咖啡,简洁背景","resolution":"1k","aspect_ratio":"1:1","quality":"medium","count":1,"output_format":"png"}{"prompt":"咖啡杯特写,蒸汽缓慢升起,镜头轻轻推进","seconds":5,"resolution":"480p","aspect_ratio":"16:9","generate_audio":false}将示例 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/capabilities | capabilities:read |
GET | /v1/capabilities/{id} | capabilities:read |
POST | /v1/quotes | tasks:create |
POST | /v1/tasks | tasks:create |
GET | /v1/tasks | tasks:read |
GET | /v1/tasks/{id} | tasks:read |
POST | /v1/tasks/{id}/cancel | tasks:cancel |
POST | /v1/assets/uploads | assets:write |
POST | /v1/assets/{id}/complete | assets:write |
GET | /v1/assets | assets:read |
GET | /v1/assets/{id} | assets:read |
DELETE | /v1/assets/{id} | assets:delete |
GET | /v1/assets/{id}/download | assets:read |
GET | /v1/usage | usage:read |
GET | /v1/webhooks | webhooks:write |
POST | /v1/webhooks | webhooks:write |
DELETE | /v1/webhooks/{id} | webhooks:write |
GET | /v1/webhooks/{id}/deliveries | webhooks:write |
POST | /v1/webhooks/{id}/rotate-key | webhooks:write |
POST | /v1/webhooks/{id}/test | webhooks:write |
POST | /v1/webhooks/{id}/replay | webhooks:write |
GET | /v1/prompt-review | tasks:create |
POST | /v1/prompt-review | tasks:create |
POST | /v1/prompt-review/assets | tasks:create |
DELETE | /v1/credentials/self | self |
提交成功返回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 投递。未启用时通过任务查询获取状态,不依赖回调完成业务流程。
创建 HTTPS 端点后,将 webhook_endpoint_id 放进任务请求。接收成功、失败和取消事件时,对原始正文校验 HMAC-SHA256。签名输入是 timestamp + "." + 原始正文,密钥为端点签名密钥。读取 X-XPosts-Timestamp、X-XPosts-Signature、X-XPosts-Event-Id、X-XPosts-Delivery-Id,验证时间窗口并按事件 ID 去重。投递测试、重放和密钥轮换见接口索引。
queued 或 running 表示任务已受理,stage 为 finalizing 时仍需等待作品保存和结算。client_request_id 和 Idempotency-Key。同一任务已经受理时会返回原编号。错误响应字段位于 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。
在工作台设置中提交反馈,附上任务或订单编号、发生时间和错误提示。不要附带密码、密钥或完整授权链接。
模型与规格可能随供应方和服务配置调整。工作台当前能力目录、输入校验及提交前报价是使用依据。
当前提供创作、查询与样本分析,不提供自动发布、私信触达或绕过平台权限获取私密内容的能力。
确认失败或取消后释放相应预留积分;状态未知或仍等待供应方确认时,先保留预留并继续核对。
客户端需要具备相应 Skill、MCP 或应用集成能力。接入指南会分别说明六类常用入口的前提,不同版本的菜单和支持程度可能不同。
access_denied 或 expired_token 时再次运行 login 获取新短码。tools/list 核对当前实际提供的工具。