APIKO

APIKO MCP 服务

在 Claude Code 和 Codex 中使用 APIKO 图像和视频模型。 该服务通过 stdio 在本地运行，并使用你自己的 APIKO API 密钥：Agent 可以 查询模型和请求字段、查看标价、生成图像和视频、跟踪任务、查看密钥的消费 情况，以及上传参考图像。

生成费用会按 API 价格从你的 APIKO 余额中扣除。服务会要求 Agent 先报价，并在每次付费调用前等待你的批准。

要求

• Node.js 18.17 或更高版本
• 从 https://apiko.app/dashboard/apikeys 获取的 APIKO API 密钥

安装

该服务以 apiko-mcp 的名称发布在 npm 上， 使用 npx -y apiko-mcp 运行。若要从源代码运行：

git clone <this repo> apiko-mcp
cd apiko-mcp
npm install
npm run build        # writes dist/index.js

并将下方的 npx -y apiko-mcp 替换为 node /absolute/path/to/apiko-mcp/dist/index.js。

Claude Code（CLI 和桌面应用）

claude mcp add apiko --scope user -e APIKO_API_KEY=sk-... -- npx -y apiko-mcp

--scope user 会将服务配置保存到 ~/.claude.json，Claude Code 桌面应用（Code 标签页）也会加载该文件。在 Claude Code 中运行 /mcp，检查 apiko 是否已连接。

Codex（CLI、IDE 扩展、桌面应用）

codex mcp add apiko --env APIKO_API_KEY=sk-... -- npx -y apiko-mcp

或者将以下内容添加到 ~/.codex/config.toml，Codex CLI、IDE 扩展 和 ChatGPT 桌面应用共用此配置文件：

[mcp_servers.apiko]
command = "npx"
args = ["-y", "apiko-mcp"]
env = { APIKO_API_KEY = "sk-..." }

如果桌面应用提示找不到 node 或 npx，请使用 which node 获取的完整 路径。

不花费任何费用进行试用

将 APIKO_MCP_READ_ONLY=1 添加到服务的 env（-e APIKO_MCP_READ_ONLY=1 或 --env APIKO_MCP_READ_ONLY=1）。此时会隐藏生成和上传工具； 模型查询、报价、任务检查和密钥用量查询仍可使用。

环境变量

变量	默认值	含义
APIKO_API_KEY	required	你的 APIKO 密钥。切勿将其粘贴到聊天中。
APIKO_MCP_READ_ONLY	off	1 会隐藏 generate_image、generate_video 和 upload_image。
APIKO_BASE_URL	https://api.apiko.app	API 基础 URL。
APIKO_SITE_URL	https://apiko.app	读取公开价格目录的位置。
HTTPS_PROXY、HTTP_PROXY、NO_PROXY	unset	仅在设置后使用。Node 内置的 fetch 会忽略这些变量，因此设置了这些变量时，服务会切换到支持代理的客户端。

工具

工具	费用	功能
search_models	免费	列出你的密钥可使用的模型及其类别、标价和模式。可按 query 和 category 筛选。
get_model	免费	获取单个模型的 input_schema（字段、枚举值、默认值）、端点、模式和价格档位。
estimate_cost	免费	根据架构验证输入，并在提交前报价。
generate_image	付费	生成图像；如果 input.images 中有参考 URL，则会编辑图像。模型支持异步运行时，会异步执行并等待，最长为 wait_seconds（默认值为 30）。
generate_video	付费	提交视频任务（POST /v1/videos）并返回其 task_id。
get_task	免费	获取任务状态、进度、结果 URL 和失败原因；最长可等待 45 秒。
check_balance	免费	查询此密钥的消费情况及其消费限额（如果有）。
upload_image	免费	上传本地 JPEG/PNG/WebP 图像（或复制公开图像 URL），并返回供参考字段使用的公开 img.apiko.app URL。

典型流程：search_models → get_model → upload_image（如果你有本地 参考图像）→ estimate_cost → 你批准 → generate_image / generate_video → get_task。

费用估算

estimate_cost（以及生成工具的 cost 字段）会返回以下结果之一：

• estimated：当价格可直接根据输入确定时返回数值，包括根据 resolution 选择的单张图片价格档位（或 gpt-image-2 的显式 WxH 尺寸）、固定的单张图片价格，以及按 resolution × duration 计算的每秒视频价格；提供 reference_video_seconds 后，也会包含参考视频的价格。
• needs_input：缺少影响价格的信息，通常是参考视频的总时长。你还会看到价格范围，以及提交时从余额中预留的金额（hold_usd）；任务结算后，会将预留金额退回至实际费用。
• token_billed：按 Token 计费（GPT Image 2.5 Flare / Sunburst、文本模型）。可能会显示 indicative_usd 作为参考，但这不是报价。
• unknown：没有公开价格或没有可靠的计价规则；切勿将其视为免费。

所有金额均为 apiko.app 公开目录中的美元标价。任务结算时，网关扣费金额为最终金额。失败的任务会自动退款。

当估算费用或其保证的最高金额超过上限，或者没有可靠的价格信息时，生成工具上的 max_cost_usd 会拒绝调用。

计费说明

• 每次调用 generate_* 都会创建一个付费任务。再次调用以检查进度会导致重复付费；请使用 get_task。
• client_request_id 可防止同一服务进程运行期间重复提交同一个调用。如果提交超时，服务不会重试：请先检查 https://apiko.app/dashboard/usage。
• 结果链接经过签名，有效期为 24 小时。上传的参考文件对任何获得链接的人公开，并会在 72 小时后删除。
• check_balance 查询的是密钥，而非账户。在 apiko.app 上创建的密钥本身没有额度限制，使用的是账户余额；只有控制面板会显示该余额（https://apiko.app/dashboard/billing）。
• 文本模型会显示在 search_models 中，但调用时应通过 OpenAI 兼容 API https://api.apiko.app/v1，而非通过此服务。

超时

Codex 默认会为每次 MCP 工具调用设置 60 秒超时，因此此处没有工具会等待超过 45 秒；对于耗时较长的任务，请使用 get_task 后续查询。少数仅支持同步调用的图像模型可能需要更长时间：如果使用此类模型，请提高 [mcp_servers.apiko] 下的 tool_timeout_sec。

开发

npm install
npm test            # builds, then runs the tests against a local mock API

src/tools.ts 保存工具逻辑，src/server.ts 基于这些逻辑构建 McpServer，与传输方式无关；src/index.ts 是 stdio 入口点。测试不会调用生产 API。