# EVA 标准视频生成 API

适用于模型广场标明支持 `openai_video` 的视频线路。标准视频按次、按秒线路通过 `/v1/videos` 调用。官转按 Token 使用单独的豆包原生协议，参见[豆包原生视频 API](/docs/published/video-generation-api)。

## 1. 查模型、分组和协议

在服务端设置 `EVA_BASE_URL`（你的 EVA 网关 HTTPS 根地址，末尾不含 `/v1`）和 `EVA_API_KEY`。除标注公开的接口外，表中的请求均携带 `Authorization: Bearer $EVA_API_KEY`。OpenAI 兼容 SDK 的 `base_url` 通常填写网关根地址加 `/v1`。运行创建示例会提交一条可能计费的任务。

| 操作 | 方法与路径 |
| --- | --- |
| 查看 Key 可用模型 | `GET /v1/models` |
| 查看公开模型与价格 | `GET /api/catalog/models?currency=CNY` |
| 查看公开协议索引 | `GET /api/pricing` |
| 查看模型绑定文档 | `GET /api/developer-docs/models/{model}`（模型 ID 做 URL 编码） |
| 查询 Key 积分 | `GET /api/usage/token/` |

先用 `/v1/models` 确认 `data[].id`，再在模型广场核对相同调用 ID 的分组、协议、分辨率和售价。通过 Key 选择有权限的分组，请求中的 `model` 填实际调用 ID。通用接口中没有用来切换分组的 `group` 参数。按次看每条报价及分辨率档位，按秒看生成时长及线路是否另计参考视频时长。

```bash
curl --fail-with-body "$EVA_BASE_URL/v1/models" \
  -H "Authorization: Bearer $EVA_API_KEY"
```

## 2. 创建视频任务

以下示例向 `POST /v1/videos` 提交 JSON，带 `Content-Type: application/json`。素材链接需替换为服务端能直接读取的 HTTPS 文件地址，签名链接应在排队和生成期间保持有效。其他线路的请求格式可在模型广场展开对应模型，打开「请求示例」并选择线路查看。

### Seedance 2.5 按秒：720P、10 秒、两张图和一段视频

```bash
curl --fail-with-body "$EVA_BASE_URL/v1/videos" \
  -H "Authorization: Bearer $EVA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "model": "seedance-2-5-second-line-l",
    "prompt": "保留参考图中的场景和主体，参考视频中的镜头缓慢向前移动",
    "seconds": 10,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "reference_assets": [
      {"media_type": "image", "url": "https://example.com/first.jpg", "role": "reference"},
      {"media_type": "image", "url": "https://example.com/second.jpg", "role": "reference"},
      {"media_type": "video", "url": "https://example.com/motion.mp4", "role": "reference"}
    ]
  }'
```

此线路支持 480P、720P、1080P 和 4–30 整数秒。参考视频实际时长单独计费。旧客户端可以保留原请求路径、模型 ID 和原来的素材 URL 字段。上面的 `reference_assets` 对应的旧格式如下，选一种格式提交。

```json
{
  "reference_images": ["https://example.com/first.jpg", "https://example.com/second.jpg"],
  "reference_videos": ["https://example.com/motion.mp4"]
}
```

仅在模型文档标明支持时使用 `reference_assets`。首尾帧线路可将图像项的 `role` 设为 `first_frame` 或 `last_frame`，首帧必填，每种角色最多一张。首尾帧单独使用。其他线路的时长、素材数量和字段以其模型说明为准。

### Seedance 2.5 Flash 按次：720P、10 秒、参考图

```json
{
  "model": "seedance-2-5-flash-request-line-n",
  "prompt": "让参考图中的场景自然动起来，镜头轻轻向前推进",
  "seconds": 10,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "reference_images": ["https://example.com/reference.jpg"]
}
```

Flash 支持 480P／720P、5–30 整数秒（排除 12 秒）。至少提供一张参考图。图片、视频和音频分别使用 `reference_images`、`reference_videos` 和 `reference_audios`，上限分别为 10、5、5，总计最多 20 个。使用本地文件时先完成上传，再将返回的 `url` 用作参考地址。

各线路可能接受不同的字段名。对同一种素材只传一种 URL 字段或一种上传 ID 字段。同一张图已通过 URL 引用时，无需再提交它的 ID。只有线路明确支持时才使用 `image_upload_ids`、`video_upload_ids` 或 `audio_upload_ids`。`multipart/form-data`、首尾帧、`face_processing` 和视频编辑等能力以目标线路文档为准。

## 3. 上传本地素材

| 操作 | 方法与路径 |
| --- | --- |
| 创建上传 | `POST /v1/video/uploads` |
| 发送分片 | `PUT /v1/video/uploads/{id}/chunks/{index}` |
| 完成上传 | `POST /v1/video/uploads/{id}/complete` |
| 查询、删除上传 | `GET`、`DELETE /v1/video/uploads/{id}` |

创建请求传 `name`、`media_type`（`image`、`video`、`audio`）、匹配的 `mime_type`、文件字节数 `size` 和整个文件的小写十六进制 `sha256`。读取响应中的 `upload.id` 与 `chunk_size`。按该大小从索引 0 开始上传，正文为原始二进制，带 `Content-Type: application/octet-stream` 与该分片的 `X-Chunk-SHA256`。成功返回 HTTP 204。最后调用完成接口，确认 `upload.ready` 为 `true` 后使用返回的 `url` 或该线路支持的上传 ID。`upload.expires_at` 是临时上传的到期时间。

以下 Python 脚本只上传素材，运行时传入文件路径和正确的 MIME 类型，例如 `python upload.py reference.png image/png`。

```python
import hashlib
import os
from pathlib import Path
import sys

import requests

base = os.environ['EVA_BASE_URL'].rstrip('/')
path = Path(sys.argv[1])
mime_type = sys.argv[2]
raw = path.read_bytes()
with requests.Session() as session:
    session.headers['Authorization'] = 'Bearer ' + os.environ['EVA_API_KEY']
    created = session.post(f'{base}/v1/video/uploads', json={
        'name': path.name, 'media_type': mime_type.split('/')[0],
        'mime_type': mime_type, 'size': len(raw),
        'sha256': hashlib.sha256(raw).hexdigest(),
    }, timeout=30)
    created.raise_for_status()
    spec = created.json()
    upload_id, chunk_size = spec['upload']['id'], spec['chunk_size']
    for index, start in enumerate(range(0, len(raw), chunk_size)):
        part = raw[start:start + chunk_size]
        response = session.put(
            f'{base}/v1/video/uploads/{upload_id}/chunks/{index}',
            data=part, timeout=30, headers={
                'Content-Type': 'application/octet-stream',
                'X-Chunk-SHA256': hashlib.sha256(part).hexdigest(),
            },
        )
        response.raise_for_status()
    completed = session.post(f'{base}/v1/video/uploads/{upload_id}/complete', timeout=60)
    completed.raise_for_status()
    result = completed.json()
    print(result['upload']['id'], result.get('url', ''))
```

## 4. 查进度、下载和取存储链接

提交后保存响应中的 `id`。用同一个 Key 查 `GET /v1/videos/{id}`。`queued`、`in_progress` 表示等待，`completed` 时可读取结果，`failed` 时停止并记录 `error`。可每 5 秒查询一次，遇到限流按 `Retry-After` 退避，设置总等待时间。

```bash
curl --fail-with-body "$EVA_BASE_URL/v1/videos/$EVA_TASK_ID" \
  -H "Authorization: Bearer $EVA_API_KEY"

curl --fail-with-body "$EVA_BASE_URL/v1/videos/$EVA_TASK_ID/content" \
  -H "Authorization: Bearer $EVA_API_KEY" -o result.mp4

curl --include "$EVA_BASE_URL/v1/tasks/$EVA_TASK_ID/video-storage" \
  -H "Authorization: Bearer $EVA_API_KEY"
```

`/v1/videos/{id}/content` 是原有下载入口。`/v1/tasks/{id}/video-storage` 可额外获取独立下载地址。读取返回的 `url` 时直接访问它，EVA Key 只用于查询 EVA 接口。

| HTTP | 含义及处理 |
| --- | --- |
| 200，`status: ready` | 读取 `url`。有 `expires_at` 时按 Unix 秒处理有效期。 |
| 202，`status: pending` | 正在处理存储，等几秒后查询同一个任务。 |
| 404 | 检查任务 ID、Key 权限和线路支持情况。 |
| 409，`task_not_successful` | 先查询视频任务状态。 |
| 410，`status: expired` | 已有地址过期。重新查一次是否可取得有效地址，仍过期时按原下载入口处理。 |
| 422，`status: unavailable` | 当前任务无法提供独立下载地址，可尝试原下载入口。 |
| 502 / 503 | 文件搬运失败或服务暂不可用，保留任务 ID，稍后查询。 |

## 5. 排查创建错误

- `400` / `422`：核对模型 ID、分辨率、时长和素材组合。精简重复的素材别名，检查 HTTPS 链接是否到期或返回网页。
- `401` / `403`：核对 Key、分组、模型权限和 IP 白名单。
- `429`：按响应退避。`5xx` 或超时且没有拿到任务 ID 时，先核对原请求结果再决定是否重试，避免重复生成和扣费。
- 提交工单时提供 EVA 请求 ID、HTTP 状态、`error.code`、`error.message`、北京时间、模型 ID 及有无任务 ID。请移除 Key、素材签名和下载票据。

