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

# 任务查询

图和视频共用一条轮询路径。创建仍走各自接口，拿到 `id` 后都用这里查进度。

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

`{id}` 就是创建响应里的 id：生图异步为 `img_…`，生视频为 `video_…`。只能查**本租户**的任务。别人的 id 或未知 id：`404`（`code` 为 `model_not_found`，`param` 为 `id`）。余额为 0 时仍可 GET。这条路径不计 RPM。

创建：

- 生图：`POST /v1/images/generations` — `async: true` 时立即返回任务 id；**默认同步**也会落任务记录（门户/管理端任务列表可见），同步成功体不含 `id`
- 生视频：`POST /v1/videos`，始终返回任务 id

> **资源路径仍可用**
>
> `GET /v1/images/{id}`、`GET /v1/videos/{id}` 与本接口返回同一份 JSON，作为别名保留。新接入请用 `/v1/tasks/{id}`。取视频文件仍走 `GET /v1/videos/{id}/content`。

## 公共字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 任务对外 id：生图 `img_…`，生视频 `video_…` |
| `object` | string | `image` 或 `video`，决定完成后的结果形状 |
| `model` | string | 对外模型 id |
| `status` | string | 见下表 |
| `progress` | int | 0–100 |
| `created_at` | int | Unix 秒 |
| `completed_at` | int \| null | 未完成时为 `null` |
| `error` | string \| null | 成功为 `null`，失败为说明字符串 |

客户可见 `status`：

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

内部「转存中」对外仍是 `in_progress`，此时还没有结果 URL；**生成成功后即已扣费**，转存失败不会退还。视频模型可关闭产物转存，完成后直接返回上游地址（无法安全直出时自动回退转存）。

## 轮询

建议 2–5 秒一次，直到 `completed` 或 `failed`。不要用创建请求一直挂着等。

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

```javascript
async function waitForTask(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_task(task_id: str) -> dict:
    while True:
        task = httpx.get(f"{base}/v1/tasks/{task_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 waitForTask(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_task(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
JsonObject waitForTask(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();
        JsonObject task = JsonParser.parseString(
            http.send(req, HttpResponse.BodyHandlers.ofString()).body()
        ).getAsJsonObject();
        String status = task.get("status").getAsString();
        if ("completed".equals(status)) return task;
        if ("failed".equals(status)) throw new IllegalStateException(String.valueOf(task.get("error")));
        Thread.sleep(3000);
    }
}
```

```csharp
async Task<JsonElement> WaitForTask(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);
    }
}
```

## 完成后：视频

`object` 为 `video`。结果在 `url`。

```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 | 视频结果地址：默认是平台转存后的稳定地址；关闭转存的模型可能直接返回上游地址 |
| `usage.seconds` | int | 计费秒数 |
| `usage.cost` | object | 可选，对外售价 |

## 完成后：生图

`object` 为 `image`。结果在 `data`（与同步生图一致）。同步多图会返回全部转存 URL；异步 worker 路径当前按单结果 URL 落一张。

```json
{
  "id": "img_a1b2c3d4e5f6",
  "object": "image",
  "model": "YOUR_IMAGE_MODEL",
  "status": "completed",
  "progress": 100,
  "created_at": 1710000000,
  "completed_at": 1710000060,
  "error": null,
  "data": [
    { "url": "https://cdn.example.com/a/xxx.png", "revised_prompt": null }
  ],
  "usage": {
    "images_generated": 1,
    "cost": { "amount": "0.2200", "currency": "CNY" }
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data` | array | 与同步生图一致；同步可多张，异步 worker 当前多为单张 |
| `data[].url` | string | 转存后的稳定地址 |
| `data[].revised_prompt` | null | 固定为 `null` |
| `usage.images_generated` | int | 实际张数 |
| `usage.cost` | object | 可选，对外售价 |

> **未完成不要当成功**
>
> 没有结果 URL 时不要给终端用户展示。生成成功后即扣费；转存失败对外是 `failed`，不会返回临时结果链。
