---
title: curl 调用
description: 不装任何 SDK，用 curl 调 1折AI 的 /v1/messages 和 /v1/chat/completions，查模型列表、测缓存、看流式输出。
---

curl 是确认"API 密钥（API key）和地址到底通没通"最快的办法。下面每条都能直接复制，先把 API 密钥放进环境变量：

```bash
export ONEZHE_API_KEY="sk-你的Key"
```

Windows 用户建议在 WSL 或 Git Bash 里跑这些命令；PowerShell 的写法见[快速开始](/docs/quickstart/)。

## Anthropic 原生：/v1/messages

```bash
curl https://1zheai.com/v1/messages \
  -H "x-api-key: $ONEZHE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 128,
    "messages": [{"role": "user", "content": "ping"}]
  }'
```

## OpenAI 兼容：/v1/chat/completions

```bash
curl https://1zheai.com/v1/chat/completions \
  -H "Authorization: Bearer $ONEZHE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "messages": [{"role": "user", "content": "ping"}]
  }'
```

## 模型列表：/v1/models

```bash
curl https://1zheai.com/v1/models \
  -H "Authorization: Bearer $ONEZHE_API_KEY"
```

## 流式输出

加 `"stream": true`，并用 `-N` 关掉 curl 的缓冲，才能看到逐段返回：

```bash
curl -N https://1zheai.com/v1/messages \
  -H "x-api-key: $ONEZHE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 128,
    "stream": true,
    "messages": [{"role": "user", "content": "从一数到五"}]
  }'
```

事件格式见[流式输出](/docs/streaming/)。

## 测缓存

同一条请求连发两次，第二次回包的 `usage.cache_read_input_tokens` 大于 0 就说明命中。`system` 里的文本需要达到模型的最小可缓存长度，完整脚本见[核对模型和用量](/docs/verify-model/)，原理见 [Prompt Caching](/docs/prompt-caching/)。

```bash
curl https://1zheai.com/v1/messages \
  -H "x-api-key: $ONEZHE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 32,
    "system": [{
      "type": "text",
      "text": "把一段至少 512 token、每次都一样的长文本放在这里",
      "cache_control": {"type": "ephemeral"}
    }],
    "messages": [{"role": "user", "content": "ping"}]
  }'
```

## 排查时加上 -i

```bash
curl -i https://1zheai.com/v1/models -H "Authorization: Bearer $ONEZHE_API_KEY"
```

`-i` 会打印状态码和响应头。状态码含义见[错误码与排错](/docs/troubleshooting/)。