---
url: https://limapi.com/docs/agents/postman.md
---
# Postman / cURL 调试

Postman 是一款界面化 HTTP 测试工具，操作直观，推荐初学者使用；cURL 则是命令行利器。本文以对话、图片、视频三类请求为例，演示如何用 Postman / cURL 调试 LimAPI 的全部接口。

::: warning 适用范围
Postman 和 cURL 仅适用于快速测试与功能验证。生产环境请使用官方 SDK，参考 [概述与快速接入](/guide/)。
:::

## cURL 与 Postman 参数对照

将 cURL 示例转换为 Postman 请求时，各参数的对应关系如下：

| cURL 参数 | Postman 界面 | 说明 |
|-----------|-------------|------|
| `curl -X POST` / `curl -X GET` | 请求方法下拉框 | 选择 HTTP 请求方法 |
| `https://<api-endpoint-url>` | URL 输入框 | API 的请求地址 |
| `-H 'Key: Value'` | Headers 标签页 | 以键值对形式配置请求头 |
| `-d '{...}'` | Body 标签页 | 配置请求体（选 raw + JSON） |

## 前提条件

在 [Portal](https://limapi.com/) 创建 API Key（`sk-` 开头），并下载安装 Postman。

## 示例一：对话接口（同步）

### cURL

```bash
curl -X POST https://limapi.com/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "messages": [
      {"role": "user", "content": "你好，介绍一下自己"}
    ]
  }'
```

### Postman 配置

1. 新建请求，方法选择 **POST**，URL 填入 `https://limapi.com/api/v1/chat/completions`。
2. 在 **Headers** 标签页添加：

| Key | Value |
|-----|-------|
| `Authorization` | `Bearer YOUR_API_KEY` |
| `Content-Type` | `application/json` |

3. 在 **Body** 标签页选择 **raw → JSON**，粘贴上面的请求体。
4. 点击 **Send**，右侧即可看到模型响应。

::: tip 流式调试
请求体中加入 `"stream": true` 可测试 SSE 流式输出。Postman 会逐块展示响应体；如需观察实时 token 流，推荐使用 cURL。
:::

## 示例二：图片生成（同步）

```bash
curl -X POST https://limapi.com/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2i",
    "prompt": "一间有着精致窗户的花店，漂亮的木质门，摆放着花朵",
    "size": "1024x1024",
    "n": 1
  }'
```

响应中的 `data[].url` 即为生成图片地址。更多参数见 [图片生成 Images](/guide/images)。

## 示例三：视频生成（异步任务）

由于视频生成耗时较长（数十秒到数分钟），接口采用**异步调用机制**，整个流程分为两步：

1. **创建任务**：调用接口创建任务，服务同步返回任务 ID；
2. **查询结果**：使用任务 ID 轮询任务状态，直到完成并获取视频 URL。

### 步骤 1：创建任务

```bash
curl -X POST https://limapi.com/api/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1-t2v",
    "prompt": "一只金毛犬在海边奔跑，阳光明媚，慢动作"
  }'
```

响应示例：

```json
{
  "request_id": "xxx",
  "output": {
    "task_id": "6eea9a05-eb65-48eb-9ed1-4d2f0908994c",
    "task_status": "PENDING"
  }
}
```

### 步骤 2：轮询任务状态

将上一步返回的 `task_id` 填入 URL：

```bash
curl -X GET https://limapi.com/api/v1/videos/6eea9a05-eb65-48eb-9ed1-4d2f0908994c \
  -H "Authorization: Bearer YOUR_API_KEY"
```

| task\_status | 含义 | 说明 |
|-------------|------|------|
| `PENDING` | 排队中 | 等待处理，继续轮询 |
| `RUNNING` | 生成中 | 继续轮询 |
| `SUCCEEDED` | 已完成 | 响应中包含 `video_url` |
| `FAILED` | 失败 | 已自动退款 |

> 💡 建议轮询间隔 5~10 秒，视频生成通常需要 1~3 分钟。完整参数见 [视频生成 Videos](/guide/videos)。

## 常用请求头速查

| Header | 值 | 说明 |
|--------|-----|------|
| `Authorization` | `Bearer sk-xxx` | 身份验证凭证，所有接口必填 |
| `Content-Type` | `application/json` | JSON 请求体必填 |

## 常见问题

### 401 Unauthorized

* 确认 Header 为 `Authorization: Bearer sk-xxx`，`Bearer` 与密钥之间有一个空格；
* 确认密钥复制完整、无首尾空格。

### Postman 中流式响应一次性返回

Postman 对 SSE 的展示为聚合结果，属正常现象；调试流式体验请以 cURL 或 SDK 为准。

### 视频任务一直 PENDING

高峰期排队时间会延长，请耐心等待数分钟；若超过 10 分钟仍为 PENDING/RUNNING，请记录 `task_id` 联系平台支持。