01
安装工具
将 Skill 安装到当前项目,选择 Agent 后重新加载。同时连接 OmniaKey MCP 或安装 CLI;Skill 本身提供操作指引。
npx skills add omniakey-com/omniakey-devtools --skill omniakey-modelsread -s OMNIAKEY_API_KEY
export OMNIAKEY_API_KEY$env:OMNIAKEY_API_KEY = [System.Net.NetworkCredential]::new('', (Read-Host 'OmniaKey API key' -AsSecureString)).Password03
验证连接即可
让 Agent 加载 omniakey-models 并执行下方检查。安装 Skill 不会自动配置 API Key 或调用工具。
确认 OmniaKey MCP 或 CLI 已就绪,列出可访问的模型并读取媒体请求的通用格式。不要提交生成任务。找到合适的模型
查询 API Key 可访问的模型,再核对模型文档中的能力和当前价格。
提交生成请求
通过同一套 OmniaKey API 调用文本及异步图片、视频或音频任务。
随时继续任务
保留任务 id 并继续查询。等待超时不会重新创建生成任务。
omniakey submit --file image.json --idempotency-key YOUR_UNIQUE_TASK_KEY
omniakey task wait TASK_ID --timeout 300
omniakey task get TASK_ID04
Skill 教会 Agent 什么
Agent Skill 只是一组指令,不是运行时。它为 Agent 提供可重复的工作流;实际调用由 MCP 服务或 CLI 完成。
先发现模型
查询当前 API Key 可用的模型,不要依赖记忆中的模型名称。
阅读模型自己的文档
构造请求前,先在模型页面确认支持的输入和当前价格。
使用幂等键
每次预期生成保留一个稳定键,避免响应丢失变成重复扣费。
恢复任务而不是重新开始
保留返回的 id 并持续查询。本地超时绝不能成为重新提交的理由。
准确报告结果
区分排队中的任务和已完成的任务,并说明任务失败或被取消。
安全处理凭据
从环境变量读取密钥,不要写进提示词、日志或仓库文件。
05
安装选项
安装器默认把 Agent Skill 写入当前项目。选择你使用的 Agent,或全局安装以便跨项目共享。
npx skills add omniakey-com/omniakey-devtools --skill omniakey-models --agent codexnpx skills add omniakey-com/omniakey-devtools --skill omniakey-models --agent claude-codenpx skills add omniakey-com/omniakey-devtools --skill omniakey-models --global06
任务状态
Skill 会在行动前检查状态。以下是它可能遇到的状态。
| 状态 | 含义 | 下一步 |
|---|---|---|
| queued | 已接受,等待执行。 | 等待或查询同一 id。 |
| processing | 正在运行;结果尚未就绪。 | 继续查询;不要重新提交。 |
| succeeded | 已完成,资源可用。 | 在签名地址过期前使用。 |
| failed | 未生成结果;预扣费用会退回。 | 查看错误,调整请求后提交新任务。 |
| canceled | 取消已完成。 | 只有仍需要输出时才提交新任务。 |
07
配合 MCP 或 CLI 使用
Skill 提供工作流,本身不会调用 API。请连接 OmniaKey MCP 服务或安装 CLI,让 Agent 具备执行路径。仅安装 Skill 不会配置密钥。
常见问题
工具会改变模型价格吗?
不会。工具复用你的 API Key 和网关计费规则。模型查询和本地格式检查不提交生成任务;文本与媒体生成可能产生费用。
等待超时后会发生什么?
远端任务不会被取消或重新提交。保留 id 并通过 task get 或 task wait 继续查询。成功结果的下载链接会过期,重新查询同一任务即可获取新链接。
Agent Skill 是托管服务吗?
不是。它是安装到项目或 Agent 环境中的一组指令文件夹。OmniaKey 不提供托管的 Skill 端点。
安装 Skill 会连接我的 API Key 吗?
不会。请单独为 MCP 服务或 CLI 配置 OMNIAKEY_API_KEY。Skill 只告诉 Agent 如何使用该工具。
Skill 会自行运行命令吗?
不会。由你的 Agent 决定何时遵循指令、调用哪些工具。生成仍需要用户提出请求。