> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 工作請求

> 一筆工作從提交到取得結果的過程。

每次生成都是一筆**工作**：用 `POST /jobs` 建立、`GET /jobs/{id}` 讀取，最後停在三種終態之一。

## 工作的狀態

| `status` | 說明 |
| - | - |
| `queued` | 已接受，等待執行；只有這個狀態可以取消。 |
| `processing` | 供應商處理中；`provider_status` 是供應商的原始狀態。 |
| `completed` | 完成；`artifacts` 內是產物。 |
| `failed` | 失敗；`error` 說明原因，未使用的預留會釋放。 |
| `canceled` | 執行前已取消，不收費。 |

`completed`、`failed` 與 `canceled` 是終態，之後工作不再變動。

## 提交

```bash theme={null}
curl https://api.blon.ai/v1/jobs \
  -H "Authorization: Bearer $BLON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model":"gpt-image-2","input":{"prompt":"A ceramic teapot on a linen table, soft morning light"},"webhook_url":"https://example.com/hooks/blon","metadata":{"order":"A-17"}}'
```

| 欄位 | 必填 | 說明 |
| - | - | - |
| `model` | 是 | [`GET /models`](https://docs.blon.ai/zh-TW/models) 的模型 id |
| `input` | 是 | 模型的輸入，以輸入 id 為鍵 |
| `webhook_url` | 否 | 工作結束時通知的公開 `https` 網址，見 [Webhooks](https://docs.blon.ai/zh-TW/how-to/webhooks.md) |
| `metadata` | 否 | 你自己的 JSON 物件，上限 1 KB，原樣回傳在工作上 |

媒體輸入為 `{ "asset_id": "…" }` 或 `{ "url": "https://…" }`，見[檔案上傳](https://docs.blon.ai/zh-TW/concepts/file-uploads.md)。

## 提交後的回應

新工作回 `202 Accepted`，`Location` header 指向該工作，`Retry-After` header 等於 `next_poll_after_seconds`。

```json theme={null}
{
  "id": "cmh2x0f6k0001qv8z9d4c1a7e",
  "object": "job",
  "model": "gpt-image-2",
  "status": "queued",
  "provider_status": null,
  "queue_position": null,
  "cancelable": true,
  "next_poll_after_seconds": 5,
  "urls": {
    "get": "https://api.blon.ai/v1/jobs/cmh2x0f6k0001qv8z9d4c1a7e",
    "cancel": "https://api.blon.ai/v1/jobs/cmh2x0f6k0001qv8z9d4c1a7e/cancel"
  },
  "input": {
    "prompt": "A ceramic teapot on a linen table, soft morning light"
  },
  "metadata": {
    "order": "A-17"
  },
  "cost": {
    "currency": "CREDITS",
    "estimated": "8",
    "charged": null,
    "refunded": "0"
  },
  "usage": null,
  "artifacts": null,
  "expires_at": null,
  "error": null,
  "webhook": {
    "url": "https://example.com/hooks/blon",
    "status": "pending",
    "attempts": 0
  },
  "idempotency_hit": false,
  "request_id": "cmh2x0f6k0001qv8z9d4c1a7e",
  "created_at": "2026-10-30T08:00:00.000Z",
  "started_at": null,
  "completed_at": null,
  "updated_at": "2026-10-30T08:00:00.000Z"
}
```

| 欄位 | 說明 |
| - | - |
| `urls.get` | 讀取工作的網址 |
| `urls.cancel` | 取消工作的網址；不能再取消時為 `null` |
| `cancelable` | 現在取消是否會成功 |
| `next_poll_after_seconds` | 下次讀取前至少等待的秒數；終態時為 `null` |
| `cost` | 提交時的 `estimated`、終態後的 `charged`（失敗或取消為 `"0"`）與 `refunded` |
| `idempotency_hit` | 以同一個 `Idempotency-Key` 取回先前的工作時為 `true` |
| `request_id` | 請求 id |

一律依 body 的 `status` 判斷，不要看 HTTP 狀態碼：冪等重放不論工作狀態都回 `200`。

## 完成後的結果

```bash theme={null}
curl https://api.blon.ai/v1/jobs/cmh2x0f6k0001qv8z9d4c1a7e \
  -H "Authorization: Bearer $BLON_API_KEY"
```

```json theme={null}
{
  "id": "cmh2x0f6k0001qv8z9d4c1a7e",
  "object": "job",
  "model": "gpt-image-2",
  "status": "completed",
  "provider_status": "succeeded",
  "queue_position": null,
  "cancelable": false,
  "next_poll_after_seconds": null,
  "urls": {
    "get": "https://api.blon.ai/v1/jobs/cmh2x0f6k0001qv8z9d4c1a7e",
    "cancel": null
  },
  "input": {
    "prompt": "A ceramic teapot on a linen table, soft morning light"
  },
  "metadata": {
    "order": "A-17"
  },
  "cost": {
    "currency": "CREDITS",
    "estimated": "8",
    "charged": "8",
    "refunded": "0"
  },
  "usage": null,
  "artifacts": [
    {
      "id": "cmh2x0g2p0002qv8zb3n5k8wd",
      "name": "default",
      "type": "image",
      "url": "https://blon.ai/api/assets/cmh2x0g2p0002qv8zb3n5k8wd?ticket=…",
      "url_expires_at": "2026-10-30T08:15:00.000Z",
      "content_type": "image/png",
      "size_bytes": 1482113,
      "width": 1024,
      "height": 1024,
      "duration_ms": null
    }
  ],
  "expires_at": "2026-11-06T08:00:00.000Z",
  "error": null,
  "webhook": {
    "url": "https://example.com/hooks/blon",
    "status": "delivered",
    "attempts": 1
  },
  "idempotency_hit": false,
  "request_id": "cmh2x0f6k0001qv8z9d4c1a7e",
  "created_at": "2026-10-30T08:00:00.000Z",
  "started_at": "2026-10-30T08:00:01.000Z",
  "completed_at": "2026-10-30T08:00:09.000Z",
  "updated_at": "2026-10-30T08:00:09.000Z"
}
```

每個產物都有 `id`，也就是 Blon 的 asset id，可以用 `{ "asset_id": "…" }` 直接當下一筆工作的輸入；`url` 是 15 分鐘有效的簽名網址（`url_expires_at`）。每次讀取工作都會重新簽發，過期就再讀一次工作。

透過 API 建立的檔案保存 7 天，時間見工作的 `expires_at`；到期後 `artifacts` 為空陣列。

## 列出工作

```bash theme={null}
curl "https://api.blon.ai/v1/jobs?limit=20&status=completed" \
  -H "Authorization: Bearer $BLON_API_KEY"
```

新的在前。以 `limit`（1–100，預設 20）分頁，`has_more` 為 `true` 時把上一頁的 `next_cursor` 帶進 `starting_after`。也可用 `status`、`model`、`created_after`、`created_before` 篩選。列表中的工作不含 `artifacts`，要產物請讀單筆工作。

## 取消工作

```bash theme={null}
curl -X POST https://api.blon.ai/v1/jobs/cmh2x0f6k0001qv8z9d4c1a7e/cancel \
  -H "Authorization: Bearer $BLON_API_KEY"
```

只有 `queued` 的工作可以取消，其餘回 `409 job_not_cancelable`。已送到供應商的工作不會取消。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.