# 飞机 API 接口文档

更新日期：2026-11-20。当前开放 **8 款视频模型和 1 款图片模型**，以下列出本站每条售价和支持参数。本站按积分计价，1 积分 = 1 元人民币。

## 开始使用

1. 在画布使用管理员提供的**邀请码注册**，或登录已有账号。新账号初始余额为 0 积分。
2. 在画布“账号”中输入**充值兑换码**，或登录本站[钱包](/wallet)兑换。邀请码用于开户，充值兑换码用于增加余额，每码只能使用一次。网络中断后先刷新余额核对，再决定下一步。
3. 在本站[API 令牌](/keys)创建自己的调用 Key，确认令牌额度、有效期和模型权限。画布内置中转站接口由账号登录自动接入，无需手工填写本站 Key。
4. 其他客户端填写本站地址和自己账号的 Key。每个账号独立结算，模型以自己的授权目录为准。

本站地址：`https://nanqiuapi.top`。兼容客户端的 Base URL 通常填写 `https://nanqiuapi.top/v1`；直接请求使用下面完整接口路径，避免重复拼接 `/v1`。其他电脑需使用实际部署的服务器地址，不能使用本机的 localhost。

画布“添加接口”保存的自定义地址和 Key 仅供当前画布账号使用，费用由对应服务商结算；它不会成为本站全体用户共享的模型，也不使用本站余额。

## 接口与鉴权

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/v1/models` | 查询当前调用 Key 可用的模型 |
| POST | `/v1/videos` | 提交一条视频生成任务（产生费用） |
| GET | `/v1/videos/{id}` | 查询本站任务状态 |
| GET | `/v1/videos/{id}/content` | 完成后下载视频 |
| GET | `/api/pricing` | 查看本站公开模型与定价配置（无需 Key） |

前四个接口统一使用请求头：

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

提交请求使用 JSON。Key 必须是本站签发的调用令牌。账号密码、网页登录会话与供应商上游 Key 均不能替代本站调用 Key。

模型列表请求（以下 curl 示例使用 Bash 续行语法）：

```bash
curl "https://nanqiuapi.top/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"
```


## 模型与价格

| 精确模型 ID | 本站售价（积分） | 时长 |
| --- | --- | --- |
| `seedance2.5（极速特价）` | 480p：4.5积分/条；720p：5.5积分/条 | 5～30 整数秒 |
| `sd2.5-w` | 480p：4积分/条；720p：7积分/条 | 4～30 整数秒 |
| `奶蛙sd2.5-M` | 480p：5积分/条；720p：6积分/条 | 5～30 整数秒 |
| `奶蛙sd2.5-V` | 720p：6积分/条 | 5～30 整数秒 |
| `官方按条SD2.5` | 480p：5.5积分/条 | 4～30 整数秒 |
| `稳定seadanco2.5-720` | 720p：6.5积分/条 | 5～30 整数秒 |
| `奶娃sd-2.5-wx` | 480p：4.5积分/条；720p：6积分/条 | 4～30 整数秒 |
| `T1-seedance-2.5` | 480p：4积分/条；720p：7.5积分/条 | 4～30 整数秒 |

以上为本站 default 分组售价。按条型号在支持的时长范围内同价。实际预扣、结算和余额以本站账本、当前分组及令牌权限为准。可在[模型广场](/pricing)和[消费记录](/usage-logs)核对。

## 视频请求参数

| 字段 | 要求 |
| --- | --- |
| `model` | 必填，精确复制上表 ID，保留中文、大小写和空格 |
| `prompt` | 必填，非空字符串；T1-seedance-2.5 最多 5000 字符，奶蛙sd2.5-V 最多 15000 字符；其他型号上限待核实 |
| `duration` / `seconds` | 必须明确填写整数秒，使用下方对应型号的示例字段；也接受 duration_seconds，同次请求只使用一种时长字段 |
| `resolution` | 建议每次明确填写；T1、奶蛙sd2.5-M 必填；只能取型号价格表中支持的分辨率 |
| `ratio` / `aspect_ratio` | 可选，使用能力表内画幅；T1-seedance-2.5 使用 ratio，其他型号示例使用 aspect_ratio；官方按条SD2.5必须省略 |
| 参考素材 | 可选，使用下方说明中的图片、视频、音频字段和公开 HTTP(S) 素材直链 |
| `n` | 省略或使用数字 1；每次只生成一条视频 |

| 精确模型 ID | 图片 / 视频 / 音频上限 | 画幅 |
| --- | --- | --- |
| `seedance2.5（极速特价）` | 30 / 10 / 10 | 16:9、9:16、1:1、4:3、3:4、21:9、auto |
| `sd2.5-w` | 30 / 10 / 10 | 16:9、9:16、1:1、4:3、3:4、21:9、auto |
| `奶蛙sd2.5-M` | 30 / 10 / 10 | 16:9、9:16 |
| `奶蛙sd2.5-V` | 30 / 10 / 10 | 16:9、9:16 |
| `官方按条SD2.5` | 30 / 0 / 10 | 使用默认画幅，省略画幅参数 |
| `稳定seadanco2.5-720` | 30 / 10 / 10 | 16:9、9:16 |
| `奶娃sd-2.5-wx` | 30 / 10 / 10 | 16:9、9:16、1:1、4:3、3:4、21:9 |
| `T1-seedance-2.5` | 30 / 0 / 10 | 16:9、9:16、1:1、4:3、3:4、21:9、3:2、2:3 |

T1-seedance-2.5 列出了常用画幅；接口允许正整数宽高比，如 16:9。官方按条SD2.5采用默认画幅。以上视频型号当前均不提供首尾帧、续写、编辑、直接文件上传或 Base64 素材接口；未列出的开关和参数不作为本站支持能力。

## 提交视频任务

下面是 Windows PowerShell 示例。将 YOUR_API_KEY 替换为自己的 Key 后执行；示例选择 **T1 720p，售价 7.50 积分/条**，执行 POST 会创建付费任务。

```powershell
$env:RELAY_API_KEY = "YOUR_API_KEY"
$baseUrl = "https://nanqiuapi.top"
$headers = @{ Authorization = "Bearer $env:RELAY_API_KEY" }
$body = @{
  model = "T1-seedance-2.5"
  prompt = "清晨的海边，镜头平稳前行"
  duration = 10
  resolution = "720p"
  ratio = "16:9"
} | ConvertTo-Json
$task = Invoke-RestMethod -Method Post -Uri "$baseUrl/v1/videos" -Headers $headers -ContentType "application/json; charset=utf-8" -Body ([Text.Encoding]::UTF8.GetBytes($body))
$task
$taskId = [Uri]::EscapeDataString([string]$task.id)
```


返回结构示意，id 与 task_id 都是**本站任务 ID**，请立即保存：

```json
{
  "id": "LOCAL_TASK_ID",
  "task_id": "LOCAL_TASK_ID",
  "object": "video",
  "model": "T1-seedance-2.5",
  "status": "queued",
  "created_at": 1794816000
}
```


以下是各型号的 JSON 请求体，发送到同一个 POST /v1/videos。替换 prompt 和其他参数即可；这里统一示例为 10 秒。

### seedance2.5（极速特价）

480p：4.5积分/条；720p：5.5积分/条 · 5～30 整数秒。时长字段使用 `duration`。

图片使用 images URL 数组；视频、音频使用 videos、audios URL 数组，也可传 {url,duration} 对象以校验真实秒数。最多30图、10视频、10音频，所有素材合计不超过30项；参考视频合计最多15秒、参考音频合计最多30秒。素材必须为公开HTTPS直链，服务商会核验实际素材时长。不支持首尾帧。

```json
{
  "model": "seedance2.5（极速特价）",
  "prompt": "清晨的海边，一位旅人沿沙滩缓缓前行，镜头平稳跟拍。",
  "duration": 10,
  "resolution": "480p",
  "aspect_ratio": "16:9"
}
```

### sd2.5-w

480p：4积分/条；720p：7积分/条 · 4～30 整数秒。时长字段使用 `duration`。

图片可用 images URL 数组；音视频使用 references 数组，包含 type、url、duration（真实素材秒数）。每类最多30图、10视频、10音频，合计50项。素材使用公开 HTTPS 直链；音视频须填写真实 duration。音频每段1.8～30.2秒，视频单段及各类型合计最多30.2秒。支持普通参考或独立首尾帧，两种方式不能混用。 提示词上限 5000 字符。

```json
{
  "model": "sd2.5-w",
  "prompt": "清晨的海边，一位旅人沿沙滩缓缓前行，镜头平稳跟拍。",
  "duration": 10,
  "resolution": "480p",
  "aspect_ratio": "16:9"
}
```

### 奶蛙sd2.5-M

480p：5积分/条；720p：6积分/条 · 5～30 整数秒。时长字段使用 `duration`。



```json
{
  "model": "奶蛙sd2.5-M",
  "prompt": "清晨的海边，一位旅人沿沙滩缓缓前行，镜头平稳跟拍。",
  "duration": 10,
  "resolution": "480p",
  "aspect_ratio": "16:9"
}
```

### 奶蛙sd2.5-V

720p：6积分/条 · 5～30 整数秒。时长字段使用 `duration`。

提示词上限 15000 字符。

```json
{
  "model": "奶蛙sd2.5-V",
  "prompt": "清晨的海边，一位旅人沿沙滩缓缓前行，镜头平稳跟拍。",
  "duration": 10,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}
```

### 官方按条SD2.5

480p：5.5积分/条 · 4～30 整数秒。时长字段使用 `seconds`。

请省略 ratio、aspect_ratio、aspectRatio、size 和 input_reference，使用上游默认画幅。

```json
{
  "model": "官方按条SD2.5",
  "prompt": "清晨的海边，一位旅人沿沙滩缓缓前行，镜头平稳跟拍。",
  "seconds": 10,
  "resolution": "480p"
}
```

### 稳定seadanco2.5-720

720p：6.5积分/条 · 5～30 整数秒。时长字段使用 `seconds`。



```json
{
  "model": "稳定seadanco2.5-720",
  "prompt": "清晨的海边，一位旅人沿沙滩缓缓前行，镜头平稳跟拍。",
  "seconds": 10,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}
```

### 奶娃sd-2.5-wx

480p：4.5积分/条；720p：6积分/条 · 4～30 整数秒。时长字段使用 `seconds`。

时长、分辨率和画幅必填。图片、视频、音频仅支持公开HTTP(S) URL字符串数组；参考视频不得长于输出视频。每次仅1条，不支持首尾帧、seed、音轨开关、materials、reference_seconds、size等未开放参数。上游近期实测因生成服务限流失败并退款，尚无成功成片验证；本次接入未进行付费生成测试。

```json
{
  "model": "奶娃sd-2.5-wx",
  "prompt": "清晨的海边，一位旅人沿沙滩缓缓前行，镜头平稳跟拍。",
  "seconds": 10,
  "resolution": "480p",
  "aspect_ratio": "16:9"
}
```

### T1-seedance-2.5

480p：4积分/条；720p：7.5积分/条 · 4～30 整数秒。时长字段使用 `duration`。

提示词上限 5000 字符。

```json
{
  "model": "T1-seedance-2.5",
  "prompt": "清晨的海边，一位旅人沿沙滩缓缓前行，镜头平稳跟拍。",
  "duration": 10,
  "resolution": "480p",
  "ratio": "16:9"
}
```


## 使用参考素材


除 T1-seedance-2.5 外的型号使用 `images`、`videos`、`audios` URL 数组；T1-seedance-2.5 使用 `referenceImages`、`referenceAudios` URL 数组。上限为 0 的素材类型不支持，不能提交。每类素材只使用一种字段名。

除 T1-seedance-2.5 外的型号也兼容 image_urls / reference_images、video_urls / reference_videos、audio_urls / reference_audios；T1-seedance-2.5 也兼容 images / image_urls / reference_images 和 audios / audio_urls / reference_audios。建议直接使用上述标准字段，避免混用别名。

示例统一使用 URL 字符串。素材必须能通过网络直接访问，不能是本地路径、localhost 地址或需要网页登录的页面。文件格式、大小、单段素材时长等未明确限制需由生成接口进一步校验。

T1-seedance-2.5 图片参考示例（example.com 为占位地址，需替换为真实可访问的素材直链）：

```json
{
  "model": "T1-seedance-2.5",
  "prompt": "清晨的海边，一位旅人沿沙滩缓缓前行，镜头平稳跟拍。",
  "duration": 10,
  "resolution": "480p",
  "ratio": "16:9",
  "referenceImages": [
    "https://example.com/assets/character.png"
  ]
}
```


画布当前的内置中转站入口开放文字和图片参考；本节音视频字段用于直接 API 调用，并不代表画布已提供相应控件。

## 查询与下载

使用提交时的账号 Key 和保存的本站任务 ID 查询。可每隔 10～15 秒查询一次；排队与生成可能需要较长时间，以接口状态为准。

```powershell
$result = Invoke-RestMethod -Method Get -Uri "$baseUrl/v1/videos/$taskId" -Headers $headers
$result
```


| status | 含义 | 处理方式 |
| --- | --- | --- |
| `queued` | 排队中 | 等待后继续查询 |
| `in_progress` | 生成中 | 等待后继续查询 |
| `completed` | 已完成 | 使用 content_url 下载 |
| `failed` | 生成失败 | 查看 error 并核对消费记录 |
| `unknown` | 暂未识别到明确状态 | 保留任务 ID，继续核对原任务 |

成功后返回 `content_url`，形式为 `/v1/videos/LOCAL_TASK_ID/content`。这是本站受鉴权保护的相对路径，下载时继续携带同一账号的调用 Key。

```powershell
if ($result.status -eq "completed") {
  Invoke-WebRequest -Uri "$baseUrl/v1/videos/$taskId/content" -Headers $headers -OutFile "video.mp4"
}
```


也可使用 curl 下载：

```bash
curl --fail-with-body "https://nanqiuapi.top/v1/videos/LOCAL_TASK_ID/content" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o video.mp4
```


查询和下载不会创建新的生成任务。任务 ID 不要替换成供应商的上游 ID。请及时保存成片，素材保留时长由上游决定。

## 常见问题

| 情况 | 处理方式 |
| --- | --- |
| 401 / 鉴权失败 | 检查本站 API Key、Bearer 请求头、令牌有效期 |
| 403 / 权限或额度提示 | 核对账号状态、模型权限、分组、账号余额和令牌额度，以返回消息为准 |
| 参数错误 | 核对精确模型 ID、时长、分辨率、画幅、素材数量及对应字段；使用本文的 JSON 视频示例 |
| 429 / 请求过多 | 等待后降低查询或调用频率；若发生在提交阶段，先确认原任务是否已受理 |
| 超时、502 或提交结果不明确 | 保留响应和时间，在任务、消费记录中核对原请求；不要自动重发 POST，以免重复生成和扣费 |
| 兑换码提交后断网 | 先刷新余额并检查充值记录，确认原兑换结果 |
| 登录数量达到上限 | 退出其他设备或网页会话后重试；联系管理员处理失效会话 |

本次文档更新核对了本站模型目录、销售价格与适配器参数；没有为验证文档执行真实付费生成。上游当前可用性与实际出片效果以调用结果为准。

## 图片生成与参考图编辑

| 精确模型 ID | 本站售价 |
| --- | --- |
| `gpt-image-2.6-sunburst原生` | 文生图 / 图生图：0.2积分/张 |

图片接口使用本站 API Key，继续从同一个账号余额按张结算。本站 1 积分 = 1 元人民币；上游的积分单位不用于本站计费。

### 文生图

POST `/v1/images/generations`，Content-Type: application/json。

```json
{
  "model": "gpt-image-2.6-sunburst原生",
  "prompt": "白色桌面上的蓝色陶瓷杯，柔和棚拍光线。",
  "n": 1,
  "size": "1024x1024"
}
```

### 参考图编辑

POST `/v1/images/edits`，JSON 可传 input_image（HTTPS 图片或 Data URL，支持数组，最多16张）；不要填写本机路径。

```json
{
  "model": "gpt-image-2.6-sunburst原生",
  "prompt": "白色桌面上的蓝色陶瓷杯，柔和棚拍光线。",
  "n": 1,
  "size": "1024x1024",
  "input_image": "https://example.com/assets/reference.png"
}
```

本地参考图也可以使用 multipart/form-data，字段 image 或 image[]。PNG / JPEG / WebP 输入图合计不超过24MB；由请求库自动生成 boundary。

```bash
curl "https://nanqiuapi.top/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.6-sunburst原生" \
  -F "prompt=保留杯子外形，改成蓝色陶瓷" \
  -F "n=1" \
  -F "image=@reference.png"
```

### 图片结果与费用

建议一次请求 n=1。size 可填1024x1024等合规尺寸；请省略未确认支持的 quality、background 和 output_format。同步请求等待返回 data 数组；每项读取 url 或 b64_json，实际返回格式以响应为准。失败请核对消费记录；遇到超时或断网，先核对结果，不要自动重复提交生成。查询视频任务的 /v1/videos 接口不适用于同步图片。上游对该原生型号标注“不保证稳定”，本站不承诺生成成功率或固定耗时。
