首次调用
注册、充值并创建密钥后,即可按下面流程接入智能体或用代码调用模型。
本页帮助用户快速上手。验证方式与限制见 验证网关,保护范围见 保护范围。
1.注册登录
打开 控制台,输入中国大陆手机号,点击「获取验证码」,输入短信验证码登录。未注册的手机号会自动创建账号。
2.充值
在 账单与充值 点击「充值」,通过支付宝付款。金额为 20 至 50000 元的整数,扣除 5% 手续费后到账。
确认余额增加后再调用。付款超时先查充值记录,避免重复付款。
3.创建密钥
进入 API 密钥,点击「新建密钥」,填写名称并创建。完整密钥只显示一次,保存后点击「我已保存」。不要将密钥放进前端、仓库或日志。
选择接入方式
在智能体中使用,选择对应指南:
通过代码接入,则继续第 4 步。
4.选择模型
在 模型页 的「对话」分组查看价格,复制模型 ID,下一步填入 ZEROSEAL_MODEL。
5.设置环境变量
在终端中执行以下命令,按提示输入密钥和模型 ID。输入密钥时不会显示字符;更换终端后需重新设置。
bash
printf 'ZeroSeal API key: '
IFS= read -r -s ZEROSEAL_API_KEY
printf '\n'
export ZEROSEAL_API_KEY
printf 'Model ID: '
IFS= read -r ZEROSEAL_MODEL
export ZEROSEAL_MODELpowershell
$secret = Read-Host "ZeroSeal API key" -AsSecureString
$env:ZEROSEAL_API_KEY = [System.Net.NetworkCredential]::new("", $secret).Password
$secret.Dispose()
Remove-Variable secret
$env:ZEROSEAL_MODEL = Read-Host "Model ID"macOS/Linux 使用 Bash 或 Zsh。PowerShell 请求示例需要 PowerShell 7+、Windows 11 或 Server 2022+(TLS 1.3 支持要求)。Windows 10 或 PowerShell 5.1 用户选择 Python 或 Go。
6.发送请求
四种示例任选一种。PowerShell 直接粘贴执行;其余保存为标签中的文件名,运行下方命令。
示例输出预算为 1024 token,包含思考与回答。余额需覆盖预扣金额,实际按用量结算。
bash
#!/usr/bin/env bash
set -e
: "${ZEROSEAL_API_KEY:?请先设置 ZEROSEAL_API_KEY}"
: "${ZEROSEAL_MODEL:?请先设置 ZEROSEAL_MODEL}"
curl --silent --show-error --max-time 120 \
--request POST 'https://gw.zeroseal.cn/v1/chat/completions' \
--header "Authorization: Bearer $ZEROSEAL_API_KEY" \
--header 'Content-Type: application/json' \
--write-out '\nHTTP %{http_code}\n' \
--data-binary @- <<JSON
{
"model": "$ZEROSEAL_MODEL",
"messages": [{"role": "user", "content": "用一句话介绍你自己。"}],
"max_completion_tokens": 1024,
"stream": false
}
JSONpowershell
if (-not $env:ZEROSEAL_API_KEY -or -not $env:ZEROSEAL_MODEL) {
throw "请先设置 ZEROSEAL_API_KEY 和 ZEROSEAL_MODEL。"
}
$body = @{
model = $env:ZEROSEAL_MODEL
messages = @(@{ role = "user"; content = "用一句话介绍你自己。" })
max_completion_tokens = 1024
stream = $false
} | ConvertTo-Json -Depth 5
$request = @{
Uri = "https://gw.zeroseal.cn/v1/chat/completions"
Method = "Post"
Headers = @{ Authorization = "Bearer $env:ZEROSEAL_API_KEY" }
ContentType = "application/json; charset=utf-8"
Body = [System.Text.Encoding]::UTF8.GetBytes($body)
TimeoutSec = 120
SkipHttpErrorCheck = $true
ErrorAction = "Stop"
}
try {
$response = Invoke-WebRequest @request
} catch {
throw "请求未完成,请检查网络或稍后重试。"
}
Write-Output ("HTTP {0}" -f $response.StatusCode)
Write-Output $response.Contentpython
import os
import sys
from openai import APIConnectionError, APIStatusError, OpenAI
api_key = os.environ.get("ZEROSEAL_API_KEY")
model = os.environ.get("ZEROSEAL_MODEL")
if not api_key or not model:
raise SystemExit("请先设置 ZEROSEAL_API_KEY 和 ZEROSEAL_MODEL。")
client = OpenAI(
api_key=api_key,
base_url="https://gw.zeroseal.cn/v1",
timeout=120.0,
max_retries=0,
)
try:
completion = client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": "用一句话介绍你自己。"}],
max_completion_tokens=1024,
stream=False,
)
except APIStatusError as error:
print(f"HTTP {error.status_code}", file=sys.stderr)
print(error.response.text, file=sys.stderr)
raise SystemExit(1)
except APIConnectionError:
raise SystemExit("请求未完成,请检查网络或稍后重试。")
print(completion.to_json())go
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"log"
"net/http"
"os"
"time"
)
func main() {
apiKey := os.Getenv("ZEROSEAL_API_KEY")
model := os.Getenv("ZEROSEAL_MODEL")
if apiKey == "" || model == "" {
log.Fatal("请先设置 ZEROSEAL_API_KEY 和 ZEROSEAL_MODEL。")
}
body, err := json.Marshal(map[string]any{
"model": model,
"messages": []map[string]string{
{"role": "user", "content": "用一句话介绍你自己。"},
},
"max_completion_tokens": 1024,
"stream": false,
})
if err != nil {
log.Fatal("构造请求失败。")
}
req, err := http.NewRequest(
http.MethodPost,
"https://gw.zeroseal.cn/v1/chat/completions",
bytes.NewReader(body),
)
if err != nil {
log.Fatal("构造请求失败。")
}
req.Header.Set("Authorization", "Bearer "+apiKey)
req.Header.Set("Content-Type", "application/json")
client := &http.Client{Timeout: 120 * time.Second}
resp, err := client.Do(req)
if err != nil {
log.Fatal("请求未完成,请检查网络或稍后重试。")
}
defer resp.Body.Close()
data, err := io.ReadAll(resp.Body)
if err != nil {
log.Fatal("读取响应失败,请稍后查看账单并重试。")
}
fmt.Printf("HTTP %d\n%s\n", resp.StatusCode, data)
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
os.Exit(1)
}
}在同一个终端中进入文件所在目录,再运行下方命令。Python 需要 3.10+,Go 需要 1.18+。
bash
bash hello.shbash
python3 -m venv .venv
.venv/bin/python -m pip install openai
.venv/bin/python hello.pypowershell
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install openai
.\.venv\Scripts\python.exe hello.pybash
go run hello.go7.查看结果
成功返回 HTTP 200,回答在 choices[0].message.content 中:
json
{
"choices": [
{
"message": {
"role": "assistant",
"content": "你好,我可以帮你回答问题。"
},
"finish_reason": "stop"
}
]
}finish_reason: length 表示达到输出上限,回答可能为空或未完成;可按需增加 max_completion_tokens。
费用见 账单与充值 的「消费」页签。请求超时仍可能计费,重试前先查记录。
常见问题
验证码有效期 5 分钟,重发间隔 60 秒。收不到时检查手机号,重发后使用最新验证码。
请求失败时查看 HTTP 状态码,以及正文中的 message 或 error.message。
| 状态码 | 处理方式 |
|---|---|
400 | 检查 JSON、模型和参数。不支持 max_completion_tokens 时,按模型页示例调整。 |
401 | 「缺少 Bearer 凭据」或「凭据无效」:检查密钥是否完整、已删除或来自海外站。 |
402 | 「余额不足」:余额不够预扣,充值或减少输出预算。余额大于零也可能触发。 |
404 | 检查地址和模型 ID;Python 的 base_url 填到 /v1。 |
429 | 减少频率或并发,等待后重试。 |
502 | 上游调用失败,稍后重试。 |
503 | 服务暂不可用;若是上游账户额度不足,换模型或联系支持,个人充值无法解决。 |
上游错误可能直接转发,具体原因以正文为准。超时、断流和费用疑问见 错误排查。
缺少环境变量时重做第 5 步;找不到 openai 时,用运行脚本的 Python 安装依赖。联系支持时提供时间、模型 ID、状态码和去除敏感信息后的错误内容,不要发送密钥或请求正文。