跳到正文

首次调用 ​

注册、充值并创建密钥后,即可按下面流程接入智能体或用代码调用模型。

本页帮助用户快速上手。验证方式与限制见 验证网关,保护范围见 保护范围。

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_MODEL
powershell
$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
}
JSON
powershell
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.Content
python
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.sh
bash
python3 -m venv .venv
.venv/bin/python -m pip install openai
.venv/bin/python hello.py
powershell
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install openai
.\.venv\Scripts\python.exe hello.py
bash
go run hello.go

7.查看结果 ​

成功返回 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、状态码和去除敏感信息后的错误内容,不要发送密钥或请求正文。