# 生成费用API文档


接入地址：`https://geekapi.net`。使用当前站点的接入密钥。

生成前提交模型和生成参数，读取预计消耗、计算公式及候选线路的费用范围。视频费用复用「视频生成」页面的计算方式，包含分辨率、原生/增强画质、参考视频时长折扣和账号价格比例；图片支持按尺寸定价和多张生成。

## 请求接口

```http
POST /api/platform/generation-cost
Authorization: Bearer sk-你的令牌
Content-Type: application/json
```

使用站点根地址，无需在路径前加 `/v1`。使用有效接入密钥，无需浏览器登录或 Cookie。此接口只计算费用，不创建生成任务、不扣费，也不读取远程素材。

```bash
curl 'https://geekapi.net/api/platform/generation-cost' \
  -H 'Authorization: Bearer sk-你的令牌' \
  -H 'Content-Type: application/json' \
  -d '{"model":"seedance-2.5","seconds":15,"resolution":"720p","videoQualityMode":"native","videoUrls":["https://your-service.example/input.mp4"],"videoDurations":[14.9]}'
```

模型值从[模型列表](https://geekapi.net/docs/platform-api/models)获取。只支持图片、视频及对应处理工具，模型能力由服务端目录识别。

## 请求字段

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 当前站点的模型值。 |
| `lineId` | number | 否 | 指定当前模型的线路 ID；省略或 `0` 时沿用账号当前选线策略。 |
| `seconds` | number / string | 否 | 视频输出秒数，大于 `0`；`-1` 表示按参考视频时长预估自动输出时长。缺省时，按秒模型可能无法计算总价。 |
| `resolution` | string | 否 | 视频清晰度，例如 `720p`、`1080p`；应与实际生成参数一致。 |
| `size` | string | 否 | 图片实际请求尺寸，例如 `1024x1024`；视频未传 `resolution` 时也可用于识别分辨率。 |
| `videoQualityMode` | string | 否 | 视频画质，`native` 原生或 `enhanced` 增强。省略时使用当前线路配置的默认档位。 |
| `generationType` | string | 否 | 视频生成模式，默认 `auto`，与[视频生成](https://geekapi.net/docs/platform-api/videos)一致。文生、图生和首尾帧模式忽略参考视频、音频。 |
| `videoUrls` | string[] | 否 | 参与本次生成的参考视频地址，按地址去重后计费。 |
| `videoDurations` | number[] | 否 | 与视频地址一一对应的时长，单位为秒，必须大于 `0`，支持小数。 |
| `audioUrls` | string[] | 否 | 参考音频地址；口型对齐等工具用于估算输出时长。 |
| `audioDurations` | number[] | 否 | 与音频地址一一对应的时长，单位为秒，必须大于 `0`。 |
| `n` | number | 否 | 图片张数，正整数，默认 `1`。视频不使用此字段。 |

请求体中仅 `model` 必填。按秒、分辨率、尺寸或素材时长计费时，需补充对应参数才能获得完整费用；信息不足时返回 `estimated: false`。

不需要填写提示词。接口从服务端读取价格、默认画质、用户选线偏好及账号倍率，客户端提交的自定义价格或倍率不参与计算。

图片示例：

```json
{"model":"aik-image-2","size":"1024x1024","n":2}
```

## 返回结果

以下为计费示意：某线路按每秒 ¥0.85 计费，输出 15 秒、输入 14.9 秒、输入价格比例 50%，预计扣除 ¥19.0825。实际价格和线路 ID 以当前账号返回为准。金额和公式统一使用人民币。

```json
{
  "success": true,
  "data": {
    "model": "seedance-2.5",
    "capability": "video",
    "estimated": true,
    "quota": 9541250,
    "minimum_quota": 9541250,
    "maximum_quota": 9541250,
    "amount": "¥19.0825",
    "formula_lines": [
      "线路 A：输出 15 秒×¥0.85/秒＋参考 14.9 秒×¥0.85/秒×50%＝¥19.0825，预计扣 ¥19.0825"
    ],
    "lines": [
      {
        "line_id": 12,
        "name": "线路 A",
        "quota": 9541250,
        "amount": "¥19.0825",
        "formula_lines": ["输出 15 秒×¥0.85/秒＋参考 14.9 秒×¥0.85/秒×50%＝¥19.0825，预计扣 ¥19.0825"]
      }
    ],
    "balance": "¥1,000.00",
    "note": "费用仅为预估，最终按成功线路、实际生成数量与服务端实测时长结算。"
  }
}
```

| 字段 | 说明 |
| --- | --- |
| `estimated` | 是否所有候选线路都已算出总价；`false` 不代表免费。 |
| `quota`、`maximum_quota` | 预计最大原始额度；无法完整计算时为 `null`。可用于预留额度。 |
| `minimum_quota` | 预计最小原始额度；自动选线有多种价格时与最大值不同，无法完整计算时为 `null`。 |
| `amount` | 可直接展示的人民币金额，多个价格显示范围，未知时为 `--`。 |
| `formula_lines` | 使用人民币金额展示的计算公式和预估说明。 |
| `lines` | 本次候选线路各自的预计额度、金额和公式；没有独立线路时 `line_id` 为 `null`。 |
| `balance` | 接入密钥所属账号的当前人民币余额展示文本。 |

`quota` 是原始额度，保留用于数值计算。人民币金额按 `quota / quota_per_unit × price` 换算，参数可通过 `/api/platform/status` 获取；示例使用 `quota_per_unit=500000`、`price=1`。本接口的金额、公式和余额始终使用人民币展示。不要解析 `amount` 做数值计算。

## 计费口径与缺失信息

- 自动选线使用账号当前策略和候选范围，排除已知算力不足或暂不可用的线路；指定 `lineId` 时只计算该线路。
- 按次视频使用一次的价格；图片先按单张额度取整，再乘以 `n`。
- 按秒视频未开启输入计费时，仅计算向上取整后的输出秒数。开启输入计费时，计算「输出秒数＋参考视频秒数×输入价格比例」，保留小数，最终额度向上取整。
- 处理工具沿用各自的时长口径和页面默认工具档位，不重复累加输入时长；口型对齐按视频与音频较短时长预估。
- 未提供必需的素材时长、价格未配置或没有候选线路时，返回 HTTP `200`、`estimated: false`、`quota: null`，在公式中说明原因。前端应展示公式及补充信息提示。
- 素材时长由调用方提供，接口不会访问素材 URL。预估不锁价、不保证线路算力或余额足够，最终费用以任务结算和使用记录为准。

## 错误处理

| HTTP 状态 | 说明 |
| --- | --- |
| `400` | JSON、字段类型、时长、张数、画质或生成模式无效，或模型不支持此费用预估。 |
| `401` | 未鉴权，或接入密钥无效、过期、停用。错误密钥不会回退到浏览器登录账号。 |
| `404` | 模型不可用，或指定线路不存在、不属于该模型、无访问权限。 |
| `429` | 请求过于频繁，请稍后重试。 |
| `502` / `503` | 费用配置或平台服务暂不可用。 |

错误响应包含 `success: false` 和 `message`。所有响应禁止缓存。