OpenCode Zen 免费模型网关：限时赠额领取与 API 接入教程

平台采用 OpenAI 兼容的调用方式，把 base_url 指向网关地址、填入控制台创建的密钥即可，原有 SDK 代码基本不用改。

接入信息怎么找

base_url 形如 https://opencode.asia/v1，最终以控制台「接入文档 / API 文档」页给出的地址为准；模型名不要凭记忆拼写，直接从控制台的模型列表复制调用 ID，免费模型一般带 free 标识。

先把密钥写进环境变量，后面的命令和脚本都从环境变量读取，避免密钥出现在代码仓库里。

export OPENCODE_ZEN_API_KEY="粘贴控制台创建的密钥"

下面是一次对话补全的最小调用，用 curl 验证密钥与网络是否通畅。示例中的模型 ID 仅为示意，请替换成控制台模型列表里实际显示的免费模型 ID。

curl https://opencode.asia/v1/chat/completions \
  -H "Authorization: Bearer $OPENCODE_ZEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-free",
    "messages": [
      {"role": "system", "content": "你是一位简洁的技术助手。"},
      {"role": "user", "content": "用一句话说明什么是 API 网关。"}
    ],
    "temperature": 0.7,
    "max_tokens": 512,
    "stream": false
  }'

用 Python 接入时直接复用 OpenAI 官方 SDK，只改 base_url 与模型名即可。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENCODE_ZEN_API_KEY"],
    base_url="https://opencode.asia/v1",
)

resp = client.chat.completions.create(
    model="deepseek-v4-flash-free",
    messages=[{"role": "user", "content": "写一个 Python 快速排序函数"}],
    temperature=0.3,
    max_tokens=512,
)

print(resp.choices[0].message.content)

关键参数说明

• model：必填，从控制台模型列表复制的调用 ID，免费模型与付费模型写法不同，写错通常直接返回模型不存在。
• messages：必填，按角色顺序排列的对话数组，system 放约束，user 放本轮问题。
• temperature：可选，编程类任务建议 0 到 0.3，创意类可调高，具体可用范围以文档为准。
• max_tokens：可选，限制单次回复长度，设置过小会导致输出被截断。
• stream：可选，设为 true 时以流式返回，客户端需要按 SSE 逐块解析。

额度耗尽与限流的典型表现

常见报错分三类：返回 401 说明密钥无效或请求头格式不对；返回 402 或额度相关提示说明免费额度已用完；返回 429 则是触发了速率或并发限制。排查顺序建议如下。

1. 先用上面的 curl 命令原样重试，确认是代码问题还是账号问题。
2. 检查 Authorization 头是否为 Bearer 加密钥，注意中间有空格，且密钥没有多余换行。
3. 到控制台用量页确认额度余额与到期时间，限时免费过期后调用会被拒绝。
4. 确认 base_url 是否带了 /v1、路径是否重复拼接成 /v1/v1/chat/completions。
5. 遇到 429 时降低并发、加入指数退避重试，并把请求间隔拉长后再测。
6. 以上都正常仍失败，说明该模型可能已移出免费名单，换一款仍在列表内的模型再试。