> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sub2api.ruilinlu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# cURL 使用 Sub2API 的命令示例

> 使用 cURL 命令行工具调用 Sub2API，适合快速测试和脚本集成，涵盖 Chat、流式与图片生成。

本页提供多种通过 cURL 调用 Sub2API 的命令示例。cURL 适合快速验证 API 可用性、编写 Shell 脚本或在 CI 流程中集成测试。

## 1. 基本 Chat Completions

<CodeGroup>
  ```bash macOS / Linux theme={null}
  curl https://sub2api.ruilinlu.com/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
      "model": "gpt-4o-mini",
      "messages": [{"role": "user", "content": "Hello!"}]
    }'
  ```

  ```powershell Windows (PowerShell) theme={null}
  Invoke-WebRequest -Uri "https://sub2api.ruilinlu.com/v1/chat/completions" `
    -Method Post `
    -Headers @{
      "Content-Type" = "application/json"
      "Authorization" = "Bearer YOUR_API_KEY"
    } `
    -Body '{
      "model": "gpt-4o-mini",
      "messages": [{"role": "user", "content": "Hello!"}]
    }'
  ```
</CodeGroup>

## 2. 将 API Key 存为环境变量后调用

<CodeGroup>
  ```bash macOS / Linux theme={null}
  export API_KEY="YOUR_API_KEY"

  curl https://sub2api.ruilinlu.com/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $API_KEY" \
    -d '{
      "model": "gpt-4o-mini",
      "messages": [{"role": "user", "content": "你好！"}]
    }'
  ```

  ```powershell Windows (PowerShell) theme={null}
  $env:API_KEY = "YOUR_API_KEY"

  Invoke-WebRequest -Uri "https://sub2api.ruilinlu.com/v1/chat/completions" `
    -Method Post `
    -Headers @{
      "Content-Type" = "application/json"
      "Authorization" = "Bearer $env:API_KEY"
    } `
    -Body '{
      "model": "gpt-4o-mini",
      "messages": [{"role": "user", "content": "你好！"}]
    }'
  ```
</CodeGroup>

## 3. 流式输出

<CodeGroup>
  ```bash macOS / Linux theme={null}
  curl https://sub2api.ruilinlu.com/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
      "model": "gpt-4o-mini",
      "messages": [{"role": "user", "content": "讲一个短故事。"}],
      "stream": true
    }' --no-buffer
  ```

  ```powershell Windows (PowerShell) theme={null}
  # PowerShell 中建议使用 Invoke-WebRequest 或第三方 curl 实现
  # 若使用原生 curl.exe（ Windows 10+ 附带），可执行：
  curl.exe https://sub2api.ruilinlu.com/v1/chat/completions `
    -H "Content-Type: application/json" `
    -H "Authorization: Bearer YOUR_API_KEY" `
    -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"讲一个短故事。"}],"stream":true}' `
    --no-buffer
  ```
</CodeGroup>

<Tip>
  `--no-buffer` 参数确保 curl 实时输出流式响应片段，而不是等待整个响应完成后一次性打印。
</Tip>

## 4. Anthropic Messages 格式

Sub2API 同时兼容部分 Anthropic Messages API 端点。示例：

<CodeGroup>
  ```bash macOS / Linux theme={null}
  curl https://sub2api.ruilinlu.com/v1/messages \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "model": "claude-3-haiku",
      "max_tokens": 256,
      "messages": [{"role": "user", "content": "你好！"}]
    }'
  ```

  ```powershell Windows (PowerShell) theme={null}
  Invoke-WebRequest -Uri "https://sub2api.ruilinlu.com/v1/messages" `
    -Method Post `
    -Headers @{
      "Content-Type" = "application/json"
      "Authorization" = "Bearer YOUR_API_KEY"
      "anthropic-version" = "2023-06-01"
    } `
    -Body '{
      "model": "claude-3-haiku",
      "max_tokens": 256,
      "messages": [{"role": "user", "content": "你好！"}]
    }'
  ```
</CodeGroup>

<Note>
  Anthropic Messages API 的可用模型与具体行为取决于上游供应商的适配实现。TODO：请在后台确认实际配置后填写。
</Note>

## 5. 图片生成

<CodeGroup>
  ```bash macOS / Linux theme={null}
  curl https://sub2api.ruilinlu.com/v1/images/generations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
      "model": "dall-e-3",
      "prompt": "一只穿着宇航服的猫在月球上漫步，卡通风格",
      "size": "1024x1024",
      "quality": "standard",
      "n": 1
    }'
  ```

  ```powershell Windows (PowerShell) theme={null}
  Invoke-WebRequest -Uri "https://sub2api.ruilinlu.com/v1/images/generations" `
    -Method Post `
    -Headers @{
      "Content-Type" = "application/json"
      "Authorization" = "Bearer YOUR_API_KEY"
    } `
    -Body '{
      "model": "dall-e-3",
      "prompt": "一只穿着宇航服的猫在月球上漫步，卡通风格",
      "size": "1024x1024",
      "quality": "standard",
      "n": 1
    }'
  ```
</CodeGroup>

## 常见问题排查

<Accordion title="curl 返回 401 Unauthorized">
  请检查 Authorization Header 拼写是否正确，Bearer 后是否多加了空格，以及 API Key 是否有效。详见 [401 排查](/troubleshooting/401)。
</Accordion>

<Accordion title="PowerShell 中 JSON 被截断或转义错误">
  PowerShell 的引号处理与 Bash 不同。建议将 JSON 保存到文件后使用 `-InFile` 参数，或在 PowerShell 7+ 中使用单引号包裹整个 JSON 字符串。
</Accordion>

<Accordion title="流式输出一次性返回全部内容">
  请确认你使用的是原生 `curl` 而非某些封装工具，并且添加了 `--no-buffer` 参数。
</Accordion>

<Accordion title="返回 404 Not Found">
  请确认 URL 路径正确（如 `/v1/chat/completions`）。若调用 Anthropic 端点失败，说明该端点可能尚未部署或模型不存在。可参考 [模型不可用排查](/troubleshooting/model-unavailable)。
</Accordion>

<Accordion title="SSL 证书验证失败">
  生产环境不建议跳过证书验证。若仅供本地调试，可添加 `-k`（curl）或 `-SkipCertificateCheck`（Invoke-WebRequest），但请谨慎使用。
</Accordion>