photontide光脉图像视频音频创作

概述

Photontide

你最终会拿到什么。 每次运行得到其中一种：

• 图片 —— 默认一张。用户指定了张数才用那个张数。
• 视频 —— 一段视频。任务还没完成时，继续跟踪同一次任务，不要再提交一次。
• 旁白 —— 一个音频文件，写到用户指定的路径。

链接、文件、状态和字段以这次接口实际返回的为准。最终格式由这次用的模型决定，交付时说明。不要事先承诺分辨率、时长或扣费金额。

把用户想要的成果做成一次最短的调用，通过用户自己的 Photontide 网关完成，并且只交还这次调用实际产生的内容。用宿主自己的理解来读需求、本地图片和已经返回的结果。用本技能选择模型、生成图片、改图、生成视频、合成语音，以及查看钱包和套餐。

只使用随包脚本

模型列表、额度、图片、改图、视频和语音都通过 scripts/client.py。连接只通过 scripts/authorize.py。不要另写 HTTP 客户端，也不要把令牌放进命令行、对话或日志。令牌只在用户私有的 ~/.photontide/credentials.json。

python scripts/client.py post /v1/images/generations

请求正文是 stdin 里的一个 JSON 对象，而且只放这一个对象。不要把用户内容、本地路径或令牌放进命令参数。

脚本只用 Python 3.7 及以上的标准库。Windows 优先用 py -3，否则用 python3。只有 python 本身是 3.7 或更新版本时才用 python。下文写成 python，按这个规则替换。

运行限制

第一次就按这四条。后面的参考只补充字段，不改这四条。

• 授权运行一条命令，把链接交给用户。 py -3 -u scripts/authorize.py。没有 py -3 时用 python3 -u。这条命令不读标准输入。宿主把它放进后台时，让它继续跑，不要再开一条。
• 图片生成、视频生成和视频轮询放进后台。 这些调用通常超过宿主大约 120 秒的前台限制，会被静默杀掉：日志是空的，退出码是 1。这不是脚本崩溃，也不是生成失败。用后台运行，等到命令结束再读输出。被掐掉时不要再 post。。
• 同一次请求只提交一次。 失败、超时、结果不合意，或命令被宿主掐掉，都先交出已有结果。不要换模型或改参数再付一次。
• 视频没完成就接着查同一次任务。 poll 每 5 秒查一次，一轮最多 30 分钟。输出 PHOTONTIDE_POLL_CONTINUE 时，立刻用打印出来的同一条路径再 poll，不要 post。

一次连接，图片视频语音通用

连接是新的、还没有、令牌失效，或者这次是卸载之后重新安装时，运行一条命令。这条命令不读标准输入。

py -3 -u scripts/authorize.py

没有 py -3 时用 python3 -u，只有 python 本身是 3.7 或更新版本时才用 python -u。

脚本会立刻打印连接页链接，并打开一次浏览器。浏览器没有打开时马上退出，链接留在输出里。浏览器打开后，这一轮大约再等一分钟。已经允许过的账号打开后进入设备页；还没允许过才点一次「允许连接」。宿主把命令放进后台时，让它继续跑，不要再开一条。两条命令一起轮询时，先拿到令牌的那条如果没来得及写入本机，后一条会看到允许已被取走。脚本发现令牌没有写进本机时，会自己重新取码并再打开一次浏览器。用户在没有脚本运行时已经点过允许，下一次图片、视频或语音命令会把这次允许收回来。

输出 PHOTONTIDE_AUTH_PENDING 时，把链接交给用户，然后重新运行同一条命令。它继续这一次允许，用户不用点第二次。浏览器已经打开过时，再运行不会再打开一次。设备码 15 分钟过期后才会重新取码。

输出 Photontide is ready 后，不要再运行这个命令。

卸载会删掉技能目录里的授权记录。重新安装会再给一次连接页链接，用来确认浏览器里当前登录的 Photontide 账号。这个账号已经允许过同一台电脑上的同一个智能体时，页面不会再显示「允许连接」，会直接进入设备页。还没允许过才会显示「允许连接」，需要点一次。不要用 ~/.photontide/credentials.json 判断是否已经授权。换过账号时，页面上如果还是旧账号，先退出并登录新账号；新账号没允许过，才会出现「允许连接」。同一份已经授权成功的安装再次运行时，可用令牌会直接输出 Photontide is ready。

没有保存过连接时，直接运行上面的命令。

脚本自己看当前进程的环境，认出 Codex、千问办公、WorkBuddy 或 Claude Code。这个产品名会显示在连接页和设备页，旁边是这台电脑的名称。把页面链接交给用户。不要向用户要令牌，也不要单独念出链接里的授权码，也不要让用户在对话里再确认一次已经点过允许。请对方确认页面上登录的是要连接的账号。这个账号已经允许过时，不要再让对方点「允许连接」。用户拒绝或页面过期时，脚本会说明。输出 PHOTONTIDE_AUTH_REQUIRED 时，重新运行上面的命令。

输出 Photontide is ready 后，先用一句话说钱包和套餐还剩多少人民币，再继续原来的请求。图片、视频和语音共用这一次连接。如果宿主只在会话开始时加载技能，安装或替换之后先开始一个新会话。

选择最短路径

• 文生图，或按本地图片图生图：读 图片(references/images.md)，调用 post /v1/images/generations。宿主只会给出本机路径，把这条路径原样放在 image。
• 文生视频、图生视频或视频生视频：读 视频(references/videos.md)，调用 post /v1/video/generations。文生视频只传提示词和分辨率。图生视频、视频生视频把参考放进 metadata.content，不要放在顶层 image 或 video。
• 做旁白：读 语音(references/speech.md)，调用 post /v1/audio/speech。用户没指定声音时先问一次，不要替用户选一个声音。

本技能只做图片、视频和旁白。不要另写音乐、声音克隆或社交搜索的接口。一次要好几样东西时，先读 一次多媒介任务(references/worked-example.md)，按依赖排顺序，每一样单独提交。

先读两个列表，不要凭记忆编模型。这两次读取都不生成、不计费：

python scripts/client.py get /v1/models
python scripts/client.py get /v1/dashboard/billing/subscriptions

/v1/models 是当前连接能用的全部模型。/v1/dashboard/billing/subscriptions 是套餐可用的模型。套餐返回里的每个模型 id 都要原样保留。id 里如果有 |，竖线左右都是模型 id 的一部分。提交图片、改图、视频或语音时，model 必须写成完整 id，例如 seedream_50_pro_photontide|PT-seedream50。只写竖线左边无法生成图片。把这份完整 id 放进 stdin 的 JSON，不要放进命令参数，也不要按 | 拆开，否则 shell 会把它当成管道。

向用户展示模型，或替用户选择模型时，按这个顺序：

1. 套餐内可用模型优先，如果有多个可用模型，要让用户选择。一个时可直接使用。
2. 套餐不足或套餐内没可用模型时从 /v1/models 中选择可用模型。如果有多个可用模型，要让用户选择，用户不选择的时候中断任务。如果只有一个可直接使用。

用户询问还剩多少时再查一次。这次读取不计费：

python scripts/client.py get /v1/dashboard/billing/subscription

remain_cny 是钱包剩余人民币，不要把它改成含套餐的总数。plan_quota_cny 是生效套餐额度，plan_used_cny 是套餐已用，套餐剩余是二者相减。plan_unlimited 为真表示套餐不限额度。plan_quota 和 plan_used 都是 0 时，没有生效套餐。用一句话说钱包还剩 ¥多少、套餐还剩 ¥多少。只有两边剩余都是 0 时，才把 topup_url 原样交给用户打开充值。套餐不限或套餐还有剩余时，不要因为钱包是 0 就要求充值。不要改成美元，也不要问用户自己还有没有额度。没有读到这些字段时说明暂时没读到，不要编一个数字。

安装完成后的 quota= 也按这个读：quota= 是钱包剩余，plan_quota= 是套餐额度，plan_used= 是套餐已用，plan_quota=unlimited 表示套餐不限额度。

保留用户的说法

把用户自己的主体、限制和否定写进提示词，只补这次接口真正需要的字段。用户没给的图片尺寸、时长、旁白声音不要补进请求。生成视频时，用户没给分辨率就传 resolution 为 480p。图生视频和视频生视频仍按视频说明带上 metadata。画幅或风格写进提示词。你补充了用户没说的风格、光线或镜头时，在回复里说明补了什么。

结果和提示词不符时，把接口实际返回的内容交给用户。这是一次结果，不要改写提示词再付一次。

本地图片和视频

用户选中的图片或视频只是一条本机路径，例如 C:/Users/asus/Desktop/4c805207f3c17eecfa3899de8873dfb8466.jpeg。不要自己转成 base64，也不要把磁盘路径交给上游。

图生图把图片路径放在 image，调用 post /v1/images/generations。图生视频把图片路径放在 metadata.content 的 image_url.url，role 为 reference_image。视频生视频把视频路径放在 metadata.content 的 video_url.url，is_asset 为 true，role 为 reference_video。这两种都调用 post /v1/video/generations，并带上 generate_audio 和 omni_reference_task_type，字段见 视频(references/videos.md)。脚本会先把本机文件上传，请求里只保留返回的 https 地址，不能放 data URL 或文件内容。asset:// 原样保留。也可以先运行 上传(references/uploads.md) 里的命令，再把打印出来的 url 放进对应的 url。正斜杠和反斜杠都可以。已经是 http(s) 地址时原样保留。一次请求只提交一次。

{"model":"列表中的完整 id","prompt":"改成夜景","image":"C:/Users/asus/Desktop/4c805207f3c17eecfa3899de8873dfb8466.jpeg"}

付费边界

列出模型、查询额度和完成授权都不生成，也不扣费。图片、改图、视频和语音会扣额度。

用户已经把要做的内容说清楚，就按这一次请求调用一次。提交前用用户自己的话说清这四件事：

1. 做什么 —— 这次要做的东西，以及由哪一个接口完成。
2. 用哪个模型 —— 用户选定的完整 id。在 WorkBuddy 里还没选定、并且能做这件事的可用模型多于一个时，先列出并请用户选，不要在这一步替用户定。套餐里没有能做这件事的，才用后面有余额的模型。
3. 只这一次 —— 同一次请求只提交一次。改了参数再提交算另外一次，要先把上一次的结果交给用户。
4. 余额不够时 —— 输出 PHOTONTIDE_TOPUP 就把下一行链接原样交给用户打开充值，说明这次没有生成，等用户说已经充好再继续。不要自己编链接。

失败、超时或结果不合意时，先把接口返回的错误交给用户，不要自动换模型或改参数再付一次。余额、充值链接和不要重复提交的规则见 额度与失败(references/billing.md)。

接着同一次任务

视频若返回未完成的任务，用 视频(references/videos.md) 里的 poll 跟踪同一个任务标识，不要再次 post。脚本每 5 秒查一次，一轮最多 30 分钟。输出 PHOTONTIDE_POLL_CONTINUE 时，立刻用同一条路径再 poll。不要因为还在排队或生成，就再提交一次。提交响应丢了、或者要判断终态时，读 任务与结果(references/tasks.md)。

交付实际返回的结果

完成后给出接口实际返回的链接、任务状态，以及用 --out 保存的文件路径。图片返回 url 就给链接；返回 b64_json 就说明这是图片数据，并按用户要的路径把解码后的文件存下来。打不开图片或播放不了音视频时，直接说明。

不要编造链接、分辨率、时长、任务状态或扣费金额。

更新

保存过网关连接之后，get、post、poll、upload 开始前会向这个网关查一次技能包。自动更新默认开着，最多每 24 小时查一次，静默替换；失败不影响这次命令。关掉之后不再改文件，最多每 24 小时提示一次当初的安装来源有没有新版本。

python scripts/client.py update
python scripts/client.py update --check
python scripts/client.py update --auto off
python scripts/client.py update --auto on

发现地址、校验、来源提示和开关见 更新与安全(references/updates-and-security.md)。

按任务读参考

分三层。第一次做这类事读第一层，选定图片、视频或旁白后读第二层，结果不对、要充值或任务丢了再读第三层。

入门

• 一次要图片、视频和旁白里的好几样：一次多媒介任务(references/worked-example.md)
• 模型 id 和两个免费列表：模型(references/models.md)

进阶

• 图片生成和改图：图片(references/images.md)
• 视频提交和轮询：视频(references/videos.md)
• 旁白：语音(references/speech.md)
• 本机图片和视频：上传(references/uploads.md)

排查

• 结果不符、模型被拒、任务还在排队：常见问题(references/faq.md)
• 任务标识、轮询和交付：任务与结果(references/tasks.md)
• 钱包、套餐、充值和失败后不要重付：额度与失败(references/billing.md)
• 技能包更新：更新与安全(references/updates-and-security.md)