*更新日期: 2026-08-26*

# 生视频

视频耗时长，对外强制异步。`POST` 立即返回任务（HTTP **200**，不是 202），不要阻塞到生成完成。后台生成等待至少约 60 分钟（按时长可更长，上限 2 小时）；超时对外 `failed`，不扣费。

**POST** `/v1/videos`

## 创建

请求体按 **Seedance / 方舟** 字段收。`duration` 与 `seconds` 同义，`ratio` 与 `aspect_ratio` 同义；同时出现时以前者为准。下表为推荐规范名；**snake_case 与 camelCase 均可**（如 `generate_audio` / `generateAudio`）。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | 是 | 对外 id |
| `prompt` | string | 是 | 文本。多模态参考里可用 `[Image 1]` / `[Video 1]` |
| `duration` | int ≥ 1 | 否 | 秒；默认 `5`。也可用 `seconds` |
| `ratio` | string | 否 | `16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `21:9` / `adaptive`。也可用 `aspect_ratio` / `aspectRatio` |
| `resolution` | `480p` \| `720p` \| `1080p` \| `4k` | 否 | 短边档位。也可用 `resolution_name` / `resolutionName` |
| `size` | string | 否 | `1280x720` 会推成比例；`720p` 会当成 `resolution` |
| `generate_audio` | boolean | 否 | 同步配音（模型需支持）。也可用 `generateAudio` |
| `watermark` | boolean | 否 | 默认 `false` |
| `camera_fixed` | boolean | 否 | 固定机位。也可用 `cameraFixed` |
| `draft` | boolean | 否 | 草稿预览（1.5 Pro） |
| `seed` | int | 否 | 随机种子 |
| `first_frame` | string | 否 | 首帧 URL。也可用 `firstFrame`、`image.url`；完整别名见下表 |
| `last_frame` | string | 否 | 尾帧 URL，与首帧组成首尾帧。也可用 `lastFrame` |
| `reference_images` | string[] | 否 | 参考图，最多视模型（Seedance 2.0 最多 9）。也可用 `referenceImages`；完整别名见下表 |
| `reference_videos` | string[] | 否 | 参考视频。也可用 `referenceVideos`；完整别名见下表 |
| `reference_audio` | string[] | 否 | 参考音频。也可用 `referenceAudio`；完整别名见下表 |

### 媒体字段别名

图 / 音 / 视频参考下列字段名都认（含各自 camelCase / snake_case）。值可以是：

| 形态 | 说明 |
|------|------|
| **公网 URL** | `http://` / `https://` 字符串，或字符串数组，或 `{ "url": "..." }` |
| **Base64** | `data:*;base64,...`，或可识别为媒体的裸 base64；会先转存 |
| **文件流** | `multipart/form-data` 上传（如 `-F input_reference[]=@a.png`）；会先转存 |

**不支持**本机文件路径。单文件约 10MB，最多 9 个文件。

| 用途 | 规范字段 | 也认（写全） |
|------|----------|--------------|
| 首帧 / 单图 | `first_frame` | `firstFrame`、`first_frame_image`、`firstFrameImage`、`init_image`、`initImage`、`image_url`、`imageUrl`、`image`（字符串）、`file`、`input_image`、`inputImage` |
| 参考图 | `reference_images` | `referenceImages`、`reference_image`、`referenceImage`、`image_urls`、`imageUrls`、`images`、`input_reference`、`inputReference` |
| 尾帧 | `last_frame` | `lastFrame`、`last_frame_image`、`lastFrameImage` |
| 参考音频 | `reference_audio` | `referenceAudio`、`reference_audios`、`referenceAudios`、`audio_url`、`audioUrl`、`audio_urls`、`audioUrls`、`audio`、`audios`、`input_audio`、`inputAudio`、`voice`、`music` |
| 参考视频 | `reference_videos` | `referenceVideos`、`reference_video`、`referenceVideo`、`video_url`、`videoUrl`、`video_urls`、`videoUrls`、`video`、`videos`、`input_video`、`inputVideo`、`clip`、`clips` |

单独传一张图（如仅 `image_url`）会当作首帧；若已有 `reference_images` / 参考音视频，则同类别名并入参考素材。首尾帧与参考素材不要混用：有参考素材时，部分模型会忽略首尾帧语义。即梦类模型会尽量映射成 `image_urls`；音频 / 参考视频是否生效取决于所选模型。

计费按创建时写入的 `duration`（或 `seconds`，默认 5）与 `resolution`。配置了**价目表**的模型按 `mode` 查表：`per_second` 为单价 × 秒数，`per_resolution` 为分辨率一口价（与秒无关），`fixed` 为分辨率 × 秒数档位一口价；否则按单价 × 秒数，`resolution` / `size` / `ratio` 可能乘价格系数。

> **AI SDK generateVideo 对不上这条路径**
>
> `experimental_generateVideo` 走 ByteDance ModelArk / AI Gateway 的任务协议，不是本平台 `POST /v1/videos`。对客请 HTTP 调本接口，或继续用 OpenAI SDK 的对话/生图。本接口同时接受 snake_case 与 camelCase 字段名。

```bash
curl https://tokenmei.com/v1/videos \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL",
    "prompt": "镜头跟随橙猫穿过雨夜街道",
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "generate_audio": false
  }'
```

```javascript
const created = await fetch("https://tokenmei.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: \`Bearer \${process.env.MOMO_API_KEY}\`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "YOUR_VIDEO_MODEL",
    prompt: "镜头跟随橙猫穿过雨夜街道",
    duration: 5,
    ratio: "16:9",
    resolution: "720p",
    generate_audio: false,
  }),
}).then((res) => res.json());
console.log(created.id, created.status);
```

```python
import os, time, httpx

base = "https://tokenmei.com"
headers = {
    "Authorization": f"Bearer {os.environ['MOMO_API_KEY']}",
    "Content-Type": "application/json",
}
created = httpx.post(
    f"{base}/v1/videos",
    headers=headers,
    json={
        "model": "YOUR_VIDEO_MODEL",
        "prompt": "镜头跟随橙猫穿过雨夜街道",
        "duration": 5,
        "ratio": "16:9",
        "resolution": "720p",
        "generate_audio": False,
    },
).json()
print(created["id"], created["status"])
```

```go
body, _ := json.Marshal(map[string]any{
	"model":          "YOUR_VIDEO_MODEL",
	"prompt":         "镜头跟随橙猫穿过雨夜街道",
	"duration":       5,
	"ratio":          "16:9",
	"resolution":     "720p",
	"generate_audio": false,
})
req, _ := http.NewRequest("POST", "https://tokenmei.com/v1/videos", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("MOMO_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
var created map[string]any
json.NewDecoder(res.Body).Decode(&created)
fmt.Println(created["id"], created["status"])
```

```php
$ch = curl_init("https://tokenmei.com/v1/videos");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("MOMO_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "model" => "YOUR_VIDEO_MODEL",
        "prompt" => "镜头跟随橙猫穿过雨夜街道",
        "duration" => 5,
        "ratio" => "16:9",
        "resolution" => "720p",
        "generate_audio" => false,
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$created = json_decode(curl_exec($ch), true);
echo $created["id"], " ", $created["status"], PHP_EOL;
```

```java
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://tokenmei.com/v1/videos"))
    .header("Authorization", "Bearer " + System.getenv("MOMO_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""
        {
          "model": "YOUR_VIDEO_MODEL",
          "prompt": "镜头跟随橙猫穿过雨夜街道",
          "duration": 5,
          "ratio": "16:9",
          "resolution": "720p",
          "generate_audio": false
        }
        """))
    .build();
String body = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString()).body();
System.out.println(body);
```

```csharp
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MOMO_API_KEY"));
var created = await http.PostAsJsonAsync("https://tokenmei.com/v1/videos", new {
    model = "YOUR_VIDEO_MODEL",
    prompt = "镜头跟随橙猫穿过雨夜街道",
    duration = 5,
    ratio = "16:9",
    resolution = "720p",
    generate_audio = false,
});
Console.WriteLine(await created.Content.ReadAsStringAsync());
```

创建响应：

```json
{
  "id": "video_a1b2c3d4e5f6",
  "object": "video",
  "model": "YOUR_VIDEO_MODEL",
  "status": "queued",
  "progress": 0,
  "created_at": 1710000000,
  "completed_at": null,
  "error": null
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 前缀固定 `video_`，用于查询 |
| `object` | string | 固定 `video` |
| `model` | string | 对外模型 id |
| `status` | string | 见下方状态表 |
| `progress` | int | 0–100 |
| `created_at` | int | Unix 秒 |
| `completed_at` | int \| null | 未完成时为 `null` |
| `error` | string \| null | 成功为 `null`，失败为说明字符串，不是 `{ message }` 对象 |

用这个 id 去查询，推荐 `GET /v1/tasks/{id}`。`GET /v1/videos/{id}` 是同一查询的别名。

图生视频（首帧）：

```json
{
  "model": "YOUR_VIDEO_MODEL",
  "prompt": "猫转头看向镜头",
  "duration": 5,
  "first_frame": "https://cdn.example.com/frame.png"
}
```

首尾帧：

```json
{
  "first_frame": "https://cdn.example.com/first.png",
  "last_frame": "https://cdn.example.com/last.png"
}
```

多模态参考（Seedance 2.0）：

```json
{
  "prompt": "让 [Image 1] 的人物走在 [Video 1] 的街道上",
  "duration": 8,
  "ratio": "16:9",
  "reference_images": ["https://cdn.example.com/person.png"],
  "reference_videos": ["https://cdn.example.com/street.mp4"]
}
```

**GET** `/v1/tasks/{id}`

只能查**本租户**的任务。别人的 id 或未知 id：`404`（`code` 为 `model_not_found`，`param` 为 `id`）。余额为 0 时仍可 GET。`GET /v1/videos/{id}` 返回同一份 JSON。

客户可见 `status`：

| 对外 | 内部在做什么 |
|------|----------------|
| `queued` | 已受理 |
| `in_progress` | 生成中，或已生成正在转存（未关闭转存的模型） |
| `completed` | 生成完成，可取 `url` |
| `failed` | 失败或超时；`error` 为说明字符串 |

内部「转存中」对外仍是 `in_progress`，此时还没有 `url`；**生成成功后即已扣费**，转存失败不会退还。上架视频模型可以关闭「产物转存」，此时完成后直接返回上游视频地址；若上游需要鉴权或不是公网 HTTPS 链接，平台会自动回退转存。直链有效期由上游决定。`error` 成功时为 `null`，失败时是字符串，不是 `{ message }` 对象。

## 轮询

建议 2–5 秒一次，直到 `completed` 或 `failed`。不要用创建请求一直挂着等。图和视频共用 `GET /v1/tasks/{id}`，详见[任务查询](/docs/tasks)。

```bash
curl https://tokenmei.com/v1/tasks/video_a1b2c3d4e5f6 \
  -H "Authorization: Bearer $MOMO_API_KEY"
```

```javascript
async function waitForVideo(id) {
  for (;;) {
    const task = await fetch(\`https://tokenmei.com/v1/tasks/\${id}\`, {
      headers: { Authorization: \`Bearer \${process.env.MOMO_API_KEY}\` },
    }).then((res) => res.json());
    if (task.status === "completed") return task;
    if (task.status === "failed") throw new Error(task.error ?? "failed");
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
}
```

```python
import os, time, httpx

base = "https://tokenmei.com"
headers = {"Authorization": f"Bearer {os.environ['MOMO_API_KEY']}"}

def wait_for_video(video_id: str) -> dict:
    while True:
        task = httpx.get(f"{base}/v1/tasks/{video_id}", headers=headers).json()
        if task["status"] == "completed":
            return task
        if task["status"] == "failed":
            raise RuntimeError(task.get("error") or "failed")
        time.sleep(3)
```

```go
func waitForVideo(id string) (map[string]any, error) {
	for {
		req, _ := http.NewRequest("GET", "https://tokenmei.com/v1/tasks/"+id, nil)
		req.Header.Set("Authorization", "Bearer "+os.Getenv("MOMO_API_KEY"))
		res, _ := http.DefaultClient.Do(req)
		var task map[string]any
		json.NewDecoder(res.Body).Decode(&task)
		res.Body.Close()
		switch task["status"] {
		case "completed":
			return task, nil
		case "failed":
			return nil, fmt.Errorf("%v", task["error"])
		}
		time.Sleep(3 * time.Second)
	}
}
```

```php
function wait_for_video(string $id): array {
    while (true) {
        $ch = curl_init("https://tokenmei.com/v1/tasks/$id");
        curl_setopt_array($ch, [
            CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("MOMO_API_KEY")],
            CURLOPT_RETURNTRANSFER => true,
        ]);
        $task = json_decode(curl_exec($ch), true);
        if ($task["status"] === "completed") return $task;
        if ($task["status"] === "failed") throw new RuntimeException($task["error"] ?? "failed");
        sleep(3);
    }
}
```

```java
Map<String, Object> waitForVideo(String id) throws Exception {
    HttpClient http = HttpClient.newHttpClient();
    while (true) {
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create("https://tokenmei.com/v1/tasks/" + id))
            .header("Authorization", "Bearer " + System.getenv("MOMO_API_KEY"))
            .GET()
            .build();
        String body = http.send(req, HttpResponse.BodyHandlers.ofString()).body();
        JsonObject task = JsonParser.parseString(body).getAsJsonObject();
        String status = task.get("status").getAsString();
        if ("completed".equals(status)) return Map.of("task", task);
        if ("failed".equals(status)) throw new IllegalStateException(String.valueOf(task.get("error")));
        Thread.sleep(3000);
    }
}
```

```csharp
async Task<JsonElement> WaitForVideo(string id) {
    using var http = new HttpClient();
    http.DefaultRequestHeaders.Authorization =
        new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MOMO_API_KEY"));
    while (true) {
        var task = await http.GetFromJsonAsync<JsonElement>($"https://tokenmei.com/v1/tasks/{id}");
        var status = task.GetProperty("status").GetString();
        if (status == "completed") return task;
        if (status == "failed") throw new Exception(task.GetProperty("error").ToString());
        await Task.Delay(3000);
    }
}
```

完成后：

```json
{
  "id": "video_a1b2c3d4e5f6",
  "object": "video",
  "model": "YOUR_VIDEO_MODEL",
  "status": "completed",
  "progress": 100,
  "created_at": 1710000000,
  "completed_at": 1710000120,
  "error": null,
  "url": "https://cdn.example.com/v/xxx.mp4",
  "usage": {
    "seconds": 5,
    "cost": { "amount": "0.5000", "currency": "CNY" }
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `url` | string | 视频结果地址，仅 `completed` 时出现；默认是平台转存后的稳定地址，关闭转存的模型可能直接是上游地址 |
| `usage.seconds` | int | 计费秒数，取创建时的 `duration` / `seconds` |
| `usage.cost` | object | 可选，对外售价 |

**GET** `/v1/videos/{id}/content`

任务未完成时 `404`（同样是 `model_not_found` / `param=id`）。完成后：

| `Accept` | 结果 |
|----------|------|
| `application/json` | `{ "url": "..." }` |
| 其他 | `302` 到结果地址（平台稳定地址或上游地址） |

```bash
curl -L https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -o clip.mp4

curl https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -H "Accept: application/json"
```

```javascript
const res = await fetch("https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content", {
  headers: {
    Authorization: \`Bearer \${process.env.MOMO_API_KEY}\`,
    Accept: "application/json",
  },
  redirect: "manual",
});
console.log(await res.json());
```

```python
import os, httpx

headers = {"Authorization": f"Bearer {os.environ['MOMO_API_KEY']}"}
print(httpx.get(
    "https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content",
    headers={**headers, "Accept": "application/json"},
).json())
open("clip.mp4", "wb").write(httpx.get(
    "https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content",
    headers=headers,
    follow_redirects=True,
).content)
```

```go
req, _ := http.NewRequest("GET", "https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("MOMO_API_KEY"))
req.Header.Set("Accept", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
io.Copy(os.Stdout, res.Body)
```

```php
$ch = curl_init("https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("MOMO_API_KEY"),
        "Accept: application/json",
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
```

```java
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content"))
    .header("Authorization", "Bearer " + System.getenv("MOMO_API_KEY"))
    .header("Accept", "application/json")
    .GET()
    .build();
System.out.println(HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString()).body());
```

```csharp
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MOMO_API_KEY"));
http.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
Console.WriteLine(await http.GetStringAsync("https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content"));
```

> **未完成不要当成功**
>
> 没有 `url` 时不要给终端用户播放。生成成功后即扣费；转存失败对外是 `failed`，不会在转存失败时返回临时结果链。关闭转存的模型返回的上游地址可能过期，建议拿到后尽快下载或自行转存。
