工作請求

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

工作的狀態

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

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

提交

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` 的模型 id
`input`	是	模型的輸入，以輸入 id 為鍵
`webhook_url`	否	工作結束時通知的公開 `https` 網址，見 Webhooks
`metadata`	否	你自己的 JSON 物件，上限 1 KB，原樣回傳在工作上

媒體輸入為 { "asset_id": "…" } 或 { "url": "https://…" }，見檔案上傳。

提交後的回應

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

{
  "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。

完成後的結果

curl https://api.blon.ai/v1/jobs/cmh2x0f6k0001qv8z9d4c1a7e \
  -H "Authorization: Bearer $BLON_API_KEY"

{
  "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 為空陣列。

列出工作

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，要產物請讀單筆工作。

取消工作

curl -X POST https://api.blon.ai/v1/jobs/cmh2x0f6k0001qv8z9d4c1a7e/cancel \
  -H "Authorization: Bearer $BLON_API_KEY"

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

開始使用

概念

操作指南

模型

協助

工作的狀態

提交

提交後的回應

完成後的結果

列出工作

取消工作

​工作的狀態

​提交

​提交後的回應

​完成後的結果

​列出工作

​取消工作

工作的狀態

提交

提交後的回應

完成後的結果

列出工作

取消工作