# 视频任务（实验性）

0.2.3 新增的实验性功能，默认关闭；需账号 OAuth 权限，生成可能消耗订阅额度或产生费用。实际可用性取决于账号资格与上游服务规则。

## 开启

在 DeepSeek Harness 设置 → xAI Grok → 媒体与任务中，选择视频开关时，卡片内会出现风险确认。取消不改设置；确认后保存，重启宿主以注册工具。确认只出现在设置页开启（包括关闭后重开）时，正常生成、查询、恢复和下载不重复询问。开启只保存设置，不生成媒体或探测额度。也可在阅读下方风险后，显式配置插件：

```yaml
videoTool: true
mediaRiskAcknowledged: true
videoModel: grok-imagine-video-1.5
videoMaxBytes: 104857600
```

- 模型首版仅支持 `grok-imagine-video-1.5`。
- 下载上限默认 100 MiB，配置允许 1–100 MiB 的整数值，与首版浏览器下载上限一致。
- 不额外保存 OAuth 凭据；继续使用现有共享登录与 xAI 专用代理。
- 没有可辨认的稳定账号 ID 时，视频任务拒绝执行，不用 access/refresh token 充当账号标识。

这是第三方非官方接入。账户资格和功能受上游服务规则影响，访问可能受限或暂停；确认不代表获得官方授权。生成可能消耗订阅额度或产生费用。文本和输入图片会发送上游，请勿上传敏感内容或无权使用的内容。停止等待不等于取消已提交的生成，也不能保证停止消耗。

新版的图片和视频一律从关闭开始，忽略旧媒体启用值。首次确认只保存本次明确选择的媒体，其余保持关闭；确认后的新选择会持久保留，不会每次重启重置，也不影响其他设置。确认项只是本机设置，不是凭据或官方许可。重置会撤销确认，即使 profile/Cordis 留有 true 开关也不会放行。关闭并保存后，会阻止后续工具、恢复和下载调用，停用本地任务列表；不会取消已提交的上游任务或删除已存任务/附件。新注册的工具需确认后重启才能出现。

## 使用流程

1. 调用 `grok_video_generate`，传入 `prompt`、`image`，可选 `duration`（6 或 10 秒）与 `resolution`（480p 或 720p）。工具默认 6 秒、480p。
2. 工具提交后返回插件 `taskId`，不是上游 `request_id`。稍后调用 `grok_video_status`，参数名为 `task_id`；每次只查询一次。
3. 本地中断或下载失败时，用 `grok_video_resume(task_id)` 恢复查询或下载，不重新生成。
4. 完成后返回普通文件附件的完整 `attachment={...}` 引用。在视频卡片或设置页任务列表使用下载入口。

输入图片支持完整会话图片附件引用、data URI，以及通过宿主 fs 权限读取的本地路径。裸图片附件 ID 仅适用于提供 `imageHostPath` 的附件后端；远程后端使用完整引用。首版拒绝远程图片 URL。官方[图生视频文档](https://docs.x.ai/developers/model-capabilities/video/image-to-video)明确支持 base64 data URI；已用一个已登录账号，将会话图片附件转换为 data URI，成功提交并保存一段 6 秒、480p 请求档位的视频；这不代表所有账号或订阅档位均可用。

## 状态与计费边界

- `pending`：上游生成中。
- `downloading`：结果下载/保存中。
- `done`：MP4 已保存为 DSH 文件附件。
- `interrupted`：查询或保存中断，可恢复；恢复不重新提交生成。
- `failed`：明确失败。
- `submission-unknown`：无法确认提交结果。不会自动重新 POST，也不保证能够找回没有收到 request ID 的上游任务。不要把查询未知状态当成重新生成。

**停止工具等待、关闭页面或卸载插件，不等于取消上游生成，也不保证停止计费。** 如需重新生成，必须作为新的请求明确提出。

## 任务、下载与隐私

任务记录按稳定账号摘要分区，位于 DSH_HOME 下的 `dsh-grok-kit` 目录，每个账号最多保留最近 50 条；这不等于删除附件存储中的视频。账号切换后不可读取或恢复其他账号的任务。

上游视频只从首版白名单 `https://vidgen.x.ai` 下载，禁止跳转，不向媒体下载请求附带 OAuth token；下载进行字节限额与 MP4 签名检查，并用附件流保存。

宿主会话的原生图片读取接口不支持文件附件，因此插件补充任务专用下载接口：

```text
GET /plugins/dsh-grok-kit/video/file?taskId=<当前账号已完成任务的UUID>
```

接口只读取已保存附件，不能指定任意文件路径或附件 ID；沿用 loopback、Host 与同源限制。视频以普通文件附件返回；新版卡片在用户点击后，通过同源接口读取并校验完整文件，支持内嵌播放与下载，二者复用同一份媒体数据。不提供 Range 请求。前端不访问带签名的上游媒体 URL。

## 能力面板

能力状态仅记录当前进程实际观察到的结果：未验证、已验证可用、权限受限、临时失败。打开面板或刷新本地任务列表不会触发媒体生成或上游权限探测。

“主循环生图”是尚未接入的 Responses 服务端能力，不代表已有的 `grok_imagine` 图片工具不可用。语音和服务端 Python 也不属于本次首版实现。

订阅额度放在“账号”页，通过 `GET /plugins/dsh-grok-kit/quota` 读取官方共享订阅池：已用/剩余百分比、报告的周期与重置时间，以及可选套餐和加量余额。打开账号页读取，成功数据在宿主内按当前账号缓存 60 秒，无后台定时轮询；刷新按钮仍遵循缓存。额度不是视频或某个模型的权限证明，接口失败不显示估算值。额度请求复用现有 OAuth 续约及代理，代理额外覆盖精确的官方计费域名 `cli-chat-proxy.grok.com`，以及 `grok.com` 上精确的 `GetGrokCreditsConfig` 回退路径（不覆盖该主机的其他路径）。回退使用同一个 OAuth bearer。重启会清空内存中的能力观察与额度缓存，但保留视频任务。

## 验证与限制

本版本需要分别验证：OAuth 权限、上游模型可用性、任务提交/恢复、所用附件后端的文件流保存与读取。遇到 403 不自动当作 token 过期，也不假定一定是订阅档位问题；429 不通过刷新令牌解决。

没有真实账号验证前，不承诺所有 SuperGrok / X Premium 档位可用。不得去掉生成媒体的水印或来源标识。