第02课：30分钟跑通第一个API调用

第02课：30分钟跑通第一个API调用

“所有的后续都从这一步开始。跑通第一个调用，你才是真正进入了AI开发的大门，而不只是在看门外的介绍。”

2.1 注册智谱AI开放平台（5分钟）

第一步：通过邀请链接注册，获得2000万Tokens礼包

打开浏览器，访问：

https://www.bigmodel.cn/invite?icode=UDPckrJ0oM9DMmhBVUu29pmwcr074zMJTpgMb8zZZvg%3D

或扫码：

智谱AI开放平台邀请二维码

使用手机号注册，国内号码可以直接使用，整个过程3分钟内完成。通过邀请链接注册，账户会自动到账 2000万Tokens 大礼包，足够你把本书所有代码案例全跑一遍还有富余。

第二步：创建API Key

登录后，进入「控制台」→「API Keys」→「新建API Key」。

给Key起个名字（比如"副业工具开发"），复制保存下来。注意：API Key只显示一次，请立刻复制保存到本地文本文件，后续所有代码都需要用到它。

格式类似：sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2.2 配置Python环境（10分钟）

安装Python（如果尚未安装）

访问 python.org 下载 Python 3.10 或以上版本。安装时勾选「Add Python to PATH」。

验证安装：

python --version
# 应该输出类似：Python 3.10.12

安装智谱AI SDK

打开命令提示符（Windows）或终端（Mac/Linux），运行：

pip install zhipuai

安装完成后验证：

python -c "import zhipuai; print('安装成功')"

配置API Key（推荐方式：环境变量）

不建议把API Key直接写在代码里（容易泄露）。推荐用环境变量：

Windows：

setx ZHIPUAI_API_KEY "你的API_KEY"

设置后重新打开命令提示符生效。

Mac/Linux：

export ZHIPUAI_API_KEY="你的API_KEY"
# 永久生效，加入 ~/.bashrc 或 ~/.zshrc
echo 'export ZHIPUAI_API_KEY="你的API_KEY"' >> ~/.bashrc

2.3 第一个API调用（10分钟）

最小可运行代码

新建一个文件 hello_glm.py，粘贴以下内容：

import os
from zhipuai import ZhipuAI

# 从环境变量读取API Key（安全）
client = ZhipuAI(api_key=os.environ.get("ZHIPUAI_API_KEY"))

# 调用GLM-4 Flash（最便宜的模型，适合测试）
response = client.chat.completions.create(
    model="glm-4-flash",
    messages=[
        {
            "role": "user",
            "content": "帮我写一条30字以内的蓝牙耳机产品广告语，突出降噪功能"
        }
    ]
)

# 输出结果
print(response.choices[0].message.content)

运行：

python hello_glm.py

预期输出类似：

沉浸音乐，隔绝世界——专业主动降噪，让你的每一刻都纯粹。

费用：这次调用消耗约60个token，费用约¥0.000003（不到一厘钱的万分之三）。

2.4 理解API调用的核心结构

response = client.chat.completions.create(
    model="glm-4-flash",    # 选择模型
    messages=[              # 对话历史（可含多轮）
        {"role": "system", "content": "你是专业文案顾问"},  # 系统角色（可选）
        {"role": "user",   "content": "用户的问题或指令"}   # 用户消息
    ],
    temperature=0.7,        # 随机性（0=确定，1=最随机），默认0.95
    max_tokens=1024,        # 最大输出长度（token数）
    top_p=0.7               # 另一种控制随机性的参数
)

几个关键参数的实际影响：

  • model：决定质量和成本。Flash最便宜，GLM-5.2最强
  • temperature：写文案用0.7-0.9（创意），写代码或提取数据用0.1-0.3（确定性）
  • max_tokens：输出越长越贵，根据需要设置上限

2.5 三个进阶调用模式

模式一：流式输出（打字机效果）

适合需要实时显示输出的界面：

response = client.chat.completions.create(
    model="glm-4-flash",
    messages=[{"role": "user", "content": "写一篇200字的产品介绍"}],
    stream=True  # 开启流式
)

for chunk in response:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)
print()  # 最后换行

模式二：多轮对话

messages = [{"role": "system", "content": "你是电商文案专家"}]

# 第一轮
messages.append({"role": "user", "content": "帮我为一款保温杯写产品标题"})
response = client.chat.completions.create(model="glm-4-flash", messages=messages)
reply1 = response.choices[0].message.content
messages.append({"role": "assistant", "content": reply1})
print("标题：", reply1)

# 第二轮（基于上文继续）
messages.append({"role": "user", "content": "好的，再为这个产品写5条卖点，每条不超过20字"})
response = client.chat.completions.create(model="glm-4-flash", messages=messages)
print("卖点：", response.choices[0].message.content)

模式三：JSON结构化输出

import json

response = client.chat.completions.create(
    model="glm-4-flash",
    messages=[{
        "role": "user",
        "content": """从以下产品描述中提取信息，以JSON格式输出：
        
产品描述：蓝牙5.0真无线耳机，续航30小时，主动降噪，IPX5防水，重量5g，颜色：黑白两色

输出JSON格式：
{
  "name": "产品名",
  "features": ["功能列表"],
  "weight": "重量",
  "colors": ["颜色列表"]
}"""
    }],
    response_format={"type": "json_object"}  # 强制JSON输出
)

data = json.loads(response.choices[0].message.content)
print(data)

2.6 常见报错与解决方法

报错信息 原因 解决方法
ModuleNotFoundError: zhipuai SDK未安装 运行 pip install zhipuai
AuthenticationError API Key无效 检查Key是否完整，无多余空格
RateLimitError 调用频率过高 在循环中加 time.sleep(0.5)
InvalidRequestError 参数错误 检查model名称、messages格式
输出为空 temperature过低或prompt有问题 调高temperature，简化prompt

很多新手卡在第一步"环境配置"上。这里有几个高频问题的详细说明：

问题一：pip install 后还是找不到包

可能原因：你的机器上有多个Python版本，pip和python对应的不是同一个版本。解决方法：用 python -m pip install zhipuai 代替 pip install zhipuai，这样确保是当前python版本在安装。

问题二：在Jupyter Notebook里运行提示环境变量读不到

Jupyter启动时继承的是它启动时的环境变量，如果你在终端里 setx 之后没有重新启动Jupyter，就会读不到。解决方法：重启Jupyter Kernel，或者在Notebook里临时设置：

import os
os.environ["ZHIPUAI_API_KEY"] = "你的API_KEY"  # 仅在这个Session有效

问题三：API调用成功但输出质量不符合预期

这通常不是API的问题，而是提示词（prompt）的问题。三个常见的优化方向：

  1. 加角色设定（“你是资深电商文案顾问”）
  2. 加具体约束（“30字以内”、“不要使用套话”）
  3. 加示例（“风格参考：‘沉浸音乐 隔绝世界’”）

2.7 成本计算：你的工具会花多少钱

计算公式：

成本 = (输入token数 + 输出token数) × 单价 / 1000

实际示例：

  • 一条500字产品文案：输入约200token + 输出约350token = 550token × ¥0.05/千 ≈ ¥0.028（不到3分钱）
  • 一份5页PDF的内容摘要：输入约3000token + 输出约500token = 3500token × ¥0.05/千 ≈ ¥0.175（不到2毛钱）

经验法则：

  • 1个中文汉字 ≈ 1.5 个token
  • 1000个中文字的输入 ≈ 1500 token ≈ ¥0.075（GLM-4 Flash）

定价参考：你向客户收¥2/篇文案，API成本¥0.03，毛利率98.5%。

2.8 用量监控：不要让成本失控

智谱AI开放平台的控制台里有详细的用量统计，建议养成定期查看的习惯。

特别是在做批量处理工具的时候，如果有一个循环写错了（比如不小心在循环里发了超长的prompt），可能会在几分钟内消耗掉大量token。建议：

设置每日用量报警：在控制台里找到「告警设置」，设置一个每日消费上限（比如¥10），超过后自动通知。

本地打印用量信息：在开发阶段，每次API调用后打印token用量：

response = client.chat.completions.create(...)

# 打印用量
usage = response.usage
print(f"本次用量：输入{usage.prompt_tokens}+输出{usage.completion_tokens}={usage.total_tokens}tokens")
print(f"估算费用：约¥{usage.total_tokens * 0.05 / 1000:.5f}")

养成这个习惯，能让你在工具上线之前就对成本有清晰的掌握，避免"工具用着用着发现亏本"的情况。

单价核算工作表：

工具类型 平均每次token GLM-4 Flash成本 合理收费 毛利率
短文案生成（100字） ~300token ¥0.015 ¥2 99.3%
长文案生成（500字） ~800token ¥0.04 ¥5 99.2%
文档摘要（3000字输入） ~5000token ¥0.25 ¥20 98.8%
合同审查（GLM-5.2） ~5000token ¥2.5 ¥100 97.5%
图像生成（CogView-4） —（按张） ¥0.08 ¥5-20 98-99%

看清楚这张表，你会发现做AI工具的利润率之高是其他任何服务都比不了的。

本课行动清单

  • [ ] 注册智谱AI开放平台并获得2000万Tokens礼包
  • [ ] 创建API Key并安全保存
  • [ ] 运行 hello_glm.py，看到第一次API输出
  • [ ] 尝试修改prompt，生成不同类型的文案，感受参数变化的效果
  • [ ] 测试一次JSON输出模式

→ 继续阅读：第03课_GLM-5.2能力全景与选型指南.md