API 接入基础

通过 API Key 接入 Glacier AI，了解异步处理流程、请求约定与七种语言的调用示例。

从自己的应用上传图片或视频，选择处理工具并获取结果。API 与工作台共用账户内的素材、积分和处理队列。

当前站点 API 地址https://app.berserkapi.com/api/v1国际版 · USD 计价

工具与余额发现可用工具、参数和当前余额 上传与素材签名直传、确认入库、管理版本 异步任务报价、提交、轮询与获取结果 水印处理保存标记、预览遮罩、读取报告 错误与重试处理限流、幂等与费用控制

创建 API Key

打开账户 → API，填写名称并选择有效期。完整的 gk_… 密钥只在创建时显示一次，请立即保存。国际版与中国版的账户、密钥、余额和存储各自独立，必须使用对应站点签发的密钥。

权限	允许的操作
`read`	查询工具、素材、任务、结果和余额，以及获取报价
`write`	包含读取权限；允许上传与修改素材、提交与取消任务、保存水印标记

请求 /api/v1/* 时携带 Authorization: Bearer YOUR_API_KEY。将密钥放在服务端环境变量或密钥管理服务中。API Key 不能用于登录、修改账户、购买积分或访问管理接口。撤销密钥会拒绝后续请求，已经提交的任务会继续处理。

准备运行环境

运行示例前设置 GLACIER_API_KEY。macOS/Linux 使用 export GLACIER_API_KEY='YOUR_API_KEY'；PowerShell 使用 $env:GLACIER_API_KEY='YOUR_API_KEY'。cURL 示例采用 Bash 语法，Windows 下可在 Git Bash 或 WSL 中运行。

下面各接口均提供 cURL、Node.js、Python、Go、Rust、Java、C# Tab。切换语言后，同页和后续页面的示例会同步选择。每段代码完成一次请求，输出 HTTP 状态与响应，并保留错误详情。

Tab	运行环境 / 依赖
cURL	cURL 7.76+、Bash；签名上传示例还需 `jq`
Node.js	Node.js 22+，内置 `fetch`，保存为 `.mjs`
Python	Python 3.10+，只使用标准库
Go	Go 1.22+，只使用标准库
Rust	Cargo 项目与 `reqwest` 0.13（启用 `blocking`，保留默认 TLS）；上传另需 `serde_json`
Java	Java 17+ 内置 HTTP 客户端；解析上传凭证另需 Jackson Databind
C#	.NET 8+ 控制台项目，内置 `HttpClient`

将 ASSET_ID、VERSION_ID、TASK_ID、QUOTE_ID 替换为前序接口实际返回的 ID。上传示例中的 sizeBytes 必须替换为文件的准确字节数。示例使用图片 2 倍超分，其他工具支持的参数以工具目录为准。

从上传到结果

查询工具目录和上传限制。
申请上传凭证，按返回的请求头将文件直接上传到签名 URL。不要向文件地址发送 API Key。
用返回的 assetId 确认上传完成。
使用 assetId、toolId、params 获取报价，仅在 problem 为 null 时继续。
保持选择不变，携带有效的 quoteId 和 Idempotency-Key 提交任务。
轮询返回的任务路径，直到 succeeded、failed 或 canceled。
获取结果；有输出文件时使用 output.downloadUrl 下载，否则读取结构化报告。

请求约定

请求与响应使用 JSON，字段为 camelCase。不需要的可选字段直接省略；契约未允许时不要传 null。204 响应没有正文。ID 是不应自行解析的小写 UUID 字符串，时间使用 ISO 8601，媒体时长和水印时间位置使用毫秒。积分是整数，不是货币金额。

每个接口的字段面板直接从后端 OpenAPI 契约构建。展开嵌套对象与联合类型，可查看完整类型、必填项与约束。也可以下载开放 API 契约，导入自己的客户端工具。