xyq

区域与站点#

在使用前，你需要明确区域，以确保正确的提供服务；

海外#

• 触发词：pippit

当确认海外区域时，你后续调用服务端时，请留意：

• 主站 API： https://www.pippit.ai/api/biz/
• CMS API（免 cookie）： https://pippit-cms.tiktok-row.org/api/internal/
• Cookie 字段：sid_tt，除了 cms 请求，其他请求都需要携带 sid_tt cookie，否则会报 401 错误

国内#

• 触发词：小云雀、xiaoyunque、xyq

当确认国内区域时，你后续调用服务端时，请留意：

• 主站 API： https://xyq.jianying.com/api/biz/
• CMS API（免 cookie）： https://pippit-cms.bytedance.net/api/internal/
• Cookie 字段：sessionid_pippitcn_web，除了 cms 请求，其他请求都需要携带 sessionid_pippitcn_web cookie，否则会报 401 错误

cms 优先策略#

• 优先使用 CMS：CMS 接口无需 cookie，且数据与主站一致；后续接口介绍环节，都会告知对应接口在 cms 是否支持
• 所有 API 均为 POST 请求，返回 JSON
• 在 cms 不支持的场景下，需使用对应的主站 API
• 并非所有时候 cms 都会正确返回，cms 仅在部分内部网络时可用，因此，在使用 cms api 时，如果超过 5s 未返回数据，你可以认为 cms 不可达，转而使用主站 API 进行请求

自动推断区域逻辑#

• 你需要根据线索自动判断用户预期访问的区域
• 通常用户在连续的和你对话过程中，不会在两个区域来回切换，所以一旦你识别了区域，在连续对话中，具有稳定性
• 在用户有和你发送链接的场景下，你可以从链接上很容易识别出区域，比如链接上有 I18N 的代表海外，有 CN 的代表国内
• 如果用户在对话中提及了关键词例如小云雀代表国内，而 pippit 代表海外
• 如果实在无法推断，比如用户说生成一个小红帽和大灰狼的视频，你很难判断是海外还是国内，此时，你可以看看 本文件同目录下的 xyq.config.json 的配置文件中，海外的还是国内的相关配置是完整的，优先用完整的；
• 如果以上都无法判断，你可以主动询问用户是想访问海外站点，还是国内站点

秘钥的管理#

• 访问 API 所需的秘钥们，保存在 本文件同目录下的 xyq.config.json 下，他们的更新周期长，他们都衍生自用户浏览器上的 cookie，换言之，当用户提供了关键的 cookie，即 本文件同目录下的 xyq.config.json 中的 oversea.sid_tt 或 domestic.sessionid_pippitcn_web 后，其他信息都可以通过相应的接口请求获取到
• 后续提到 config、config.json，默认都是指的 本文件同目录下的 xyq.config.json
• 如果 本文件同目录下的 xyq.config.json 路径不存在，说明是初始化场景，你需要帮我创建出来，该 config 文件的初始态如下：

json

{
    "oversea": {
        "sid_tt": "",
        "uid": "",
        "workspace_id": "",
        "space_id": ""
    },
    "domestic": {
        "sessionid_pippitcn_web": "",
        "uid": "",
        "workspace_id": "",
        "space_id": ""
    }
}

• 当遇到 401 错误、用户未登录、用户不存在、无权限等，需提醒用户重新获取 cookie：

  • 海外场景：登录 https://www.pippit.ai/home → 通过 F12 打开控制台 → Application → Cookies → 复制 sid_tt
  • 国内场景：登录 https://xyq.jianying.com → 通过 F12 打开控制台 → Application → Cookies → 复制 sessionid_pippitcn_web
  • 你可以把这张图也一并提供给用户，上面有图文获取 cookie 的教程， https://cdna-1253404032.cos.ap-beijing.myqcloud.com/img/copy-cookie.png
  • 你告诉用户，拷贝完 cookie 后，发送给你

• 当你收到用户给你的 cookie，你需要更新到 本文件同目录下的 xyq.config.json 中，在 本文件同目录下的 xyq.config.json 里路径分为：

  • 海外： oversea.sid_tt
  • 国内： domestic.sessionid_pippitcn_web

生成历史链接解析#

有时候，用户会分享给你一个生成历史的链接，其 url 种包含 /generate-history，如下： https://pippit-cms.bytedance.net/#/generate-history?generate_id=xxx&region=I18N&user_id=xxx 虽然它域名是 bytedance.net，但它并不是上文提及的 cms api，但是它是一个 cms 管理后台的链接;

用户发送这个链接，通常是想指代一次生成任务，你只需要提取其中的关键信息

• generate_id = thread_id
• region 指的是区域

你可以通过 API /v1/agent/get_thread 来获取本 thread 的详情，然后回答用户的问题

用户生成要求#

生图生视频#

当用户向你发出一个生图或者生视频的要求时，比如用户说 “帮我生成一张豆浆的图片”，此时你应该：

• 如果用户的指令里，没有很明确的意图是要生成图片还是视频，你需要询问用户
• 通过 /v1/agent/submit_run 的方式提交用户的请求，提交内容最好能明显识别出来是要生图还是生视频
• 检查提交结果，如果有异常，告诉用户
• 如果提交成功，则启动一个 subagent (spawn 一个新 session) 去查询生成结果，因为结果需要轮询，且视频场景通常很慢；
  • 轮询结果的方式是使用 /v1/agent/get_thread api 来查询；所查询的 thread 即你刚才 submit_run 时的 thread；
  • 在每次轮询回来的数据里，你需要留意的是刚才 submit_run 对应的 run_id 的数据，判断 run 是否达到终结态，否则需要一直轮询 (当然，最多 10 分钟没结果就算了)，轮询频次可以是 20s 这样的间隔
  • 当达到终结态时，你需要把对应 run 的 assistant 消息里的信息或者生成产物(asset_id 和下载链接) 告诉用户
  • 如果达到终结态，如果没有结果，而是返回了别的信息，比如 questionaire 等，你也需要告知用户
  • 由于这些轮询行为你会扔个一个 subagent 来处理，请记住告诉它充足的信息，比如如何请求接口，建议当达成终结态后，让 subagent 返回完整的 thread 数据给你，以便你做出准确的响应

当用户要延续之前某次 thread 继续对话时，你只需 /v1/agent/submit_run 在延续之前的 thread_id，其他逻辑和上述要求一样。

记住如果用户有生图生视频指令，无论成功与否，你都要回复用户，给用户通知；通知用户时，如果有产物链接，请以 markdown 格式回复给用户

API 接口#

获取 uid workspace_id space_id 等信息#

注：并非所有 API 调用场景都需要 uid workspace_id space_id，你只需遵循 API 要求，按需获取这些信息。

当需要这些信息事，你可以：

• 可以先判断 本文件同目录下的 xyq.config.json 中是否有 uid、workspace_id、space_id 等信息，如果有，直接使用；如果没有，需要先获取一次，然后保存到 本文件同目录下的 xyq.config.json 中；
• 注意，oversea 和 domestic 是不一样的，他们在 本文件同目录下的 xyq.config.json 中的存放位置也不一样

当 本文件同目录下的 xyq.config.json 中没有相关信息，或者你使用接口明确这些信息不可用时候，你可以通过以下方式来获取/更新它们： 国内获取 uid workspace_id space_id 等信息的流程

• uid 获取：通过 post https://xyq.jianying.com/commerce/v1/subscription/user_info，携带 sessionid_pippitcn_web cookie，另外 body 里放入 "aid" : 795647，然后从返回的数据中获取 uid
• workspace_id 和 space_id 获取：通过 post https://xyq.jianying.com/api/web/v1/workspace/get_user_workspace，body 里放入 {uid}，以及 header 携带 sessionid_pippitcn_web cookie，然后从返回的数据中获取 workspace_id 和 space_id

海外获取 uid workspace_id space_id 等信息的流程

• uid 获取：通过 get https://www.pippit.ai/home，一定要注意的是，get 的时候，headers 的 cookie 里一定要携带 sid_tt 这个 cookie，从你获得的 html 数据中，找到 __userInfoStringify 字符串，这个字符串内部，有 user_id (即为 uid)、workspace_id、space_id 等信息 (由于这个 html 有 200k 字符，建议你启一个 subagent 专门获取)

/v1/agent/get_thread#

• 作用：查询 thread_id 详情
• cms 支持
• 参数：
  • scopes: ["run_list.entry_list"]（固定）
  • thread_id: 必填，未提供则询问用户
• 返回关注：data.thread.run_list 内的数据

关于 /v1/agent/get_thread 返回数据的详述

当你获得了 /v1/agent/get_thread 的返回的 json 数据后，你可以按以下方式，了解其中的信息：

• 名词解释：所谓 thread 即在一个对话窗口里的一轮或多轮对话，而每一轮对话，为一个 run
• 拿到数据后，你首先你需要进入 data.thread.run_list 里，所有的 run 数据都在这里了，所以这是最关键的数据
• log_id：从返回数据中，找到最后一条 execute_log_id，即为 log_id，其实每一轮 run 都有个 log_id，如果没特殊指明，默认取最后一条 run 的 log_id
• 每个 run 里，有多个 message，其中 role 代表消息的发送者，user 代表用户，assistant 代表助手，而 tool 则是中间调用的工具；
• 每个 run 都有个 state，state 的取值为 1、2、3、4、5，分别表示 run 的状态：
  • 1: Submitted（已提交）
  • 2: Working（正在处理中）
  • 3: Completed（[终态]已完成）
  • 4: Failed（[终态]已完成但失败）
  • 5: Canceled（[终态]在完成前被取消）
• 通常，你只需要关心最后一个 run 的状态，因为前序 run 通常是终结态，因为不终结，无法启动后续的 run
• message 中，有很多 part，生成的视频、图片产物也在这些 part 里，如 biz/x_data_video、biz/x_data_image 等，你需要关注其中的 asset_id 和 download_url；asset_id 是视频、图片的唯一标识，download_url 是下载视频、图片的 url；

/v1/agent/submit_run#

• 作用：向 agent 提交消息/请求，通常用于生成图片、视频
• 前置依赖：uid、workspace_id、space_id，请先确保获取了
• cms 不可用

当你明确要提交的消息后，可以调用本文件同级 scripts/generate_submit_run_body.sh 脚本，生成提交的请求体，然后发送即可；注意，该脚本执行时，-r domestic 表示国内站 -r oversea 表示海外站，-p 是要提交的消息

关于 thread_id 如何获取：如果你是要在之前已经存在的对话中，继续提交内容，则要延续之前的 thread_id，在 scripts/generate_submit_run_body.sh 时，可额外提供 -t 参数提供你要延续的 thread_id；但如果是新对话场景，则无需提供

agent 生成的内容，并不会在 post 请求后返回，因为是一个异步的过程；例如，生成视频可能需要几分钟，而生成图片可能需要几十秒；所以，如果你需要获取内容，则要通过 /v1/agent/get_thread 接口查询；记住，你需要记得刚才的 thread_id 是啥，因为查询时，你需要提供 thread_id，才能获取到对应的内容

这个接口查询到的数据，自然包含你刚才提交的 message;