API / IMAGE-TO-IMAGE / BETAv0.1 contract

圖生圖 REST API，
從 task 到結果。

為開發者準備的非同步影像流程：POST 建立 task、GET 輪詢狀態，再把 output ref 接回自己的產品。先把邊界說清楚，再一起驗證 provider 能力。

非同步 task contractowner-scoped statusfail closed provider 邊界

REQUEST / TASK / RESPONSE

LIVE CONTRACT

YOUR PRODUCT → CREBOTS API

$ curl -X POST /api/image-to-image
  -H "Authorization: Bearer $API_KEY"

→ 201
  { "id": "task_…", "status": "queued",
    "pollingUrl": "/api/image-to-image/task_…" }

$ GET /api/image-to-image/task_…
→ queued → processing
  → completed | failed

providernot configured / 503

responseredacted status

next steppoll or integrate

01 / DEVELOPER VALUE

把影像生成變成一個你能控制的 API 邊界。

不是一個假裝隨時有結果的 demo；是一組可以被你的產品流程理解、輪詢與驗證的 contract。

PRODUCT TEAMS

把生成能力藏在你的 UX 裡

用 task id 與狀態輪詢組出自己的 loading、重試與結果頁，不把使用者綁在另一個工具介面。

AUTOMATION

讓非同步成為流程的一部分

建立請求與取得結果分開處理，讓你的後端可以按自己的節奏併發、輪詢與記錄。

EARLY BUILDERS

從可驗證的 contract 開始

先接穩 input、status、error 與 output ref，再依 provider 可用性擴充真實生成能力。

02 / ASYNC PIPELINE

POST 一次，輪詢到你真正需要的狀態。

四個狀態都是真實 contract；展示切換只改變文件示意，不會在瀏覽器觸發 provider 或虛構生成。

TASK CONTRACT / IMAGE-TO-IMAGE

ASYNC

01 / create

先建立，再輪詢

POST /api/image-to-image
Authorization: Bearer <api-key>

{
  "sourceImageRef": "…",
  "prompt": "…",
  "generationParams": { "…": "…" }
}

→ 201 {
  "id": "task_…",
  "status": "queued",
  "pollingUrl": "/api/image-to-image/task_…"
}

合法請求的設計回應是 `201 queued`。目前 provider 尚未配置，真實請求會 fail closed 並回 `503 IMAGE_PROVIDER_NOT_CONFIGURED`，不會虛構 task 或 output。

02 / poll

GET task status

/:taskId

queuedresponse

已建立 task，等待 provider。

GET /api/image-to-image/task_…

{
  "id": "task_…",
  "status": "queued",
  "createdAt": "…",
  "updatedAt": "…",
  "errorMessage": null,
  "outputImageRef": null
}

API boundary

狀態 response 不暴露 prompt、來源圖或 generation params；task 只能由建立它的 user／API key scope 讀取。

03 / DATA BOUNDARY

你的 key 與 task，不是公開 demo 的狀態。

對開發者來說，能知道哪些資料不會被 response 帶走，和知道 endpoint 怎麼呼叫一樣重要。

只呈現目前程式碼可驗證的 hash、scope 與 redaction；不擴張成未核准的法律承諾。

DATA BOUNDARY / 04

可從現有 contract 證明的隱私邊界

VERIFIED IN CODE

API key storage

只保存不可逆 hash

API key secret 只在建立時回傳；資料庫保存 hash，後續請求以 Bearer key 驗證。

owner scope

user／key scope 隔離

task 狀態查詢會綁定建立 task 的 user 與 API key，未知或撤銷的 key 不會讀到資料。

response boundary

狀態回應做 redaction

公開 contract 只帶 status、時間、錯誤與 output ref，不帶 prompt、來源圖或 generation params。

以上是目前程式碼可驗證的範圍；本頁不額外承諾「不訓練」、固定保存期限或自動刪除等法律／生命週期條款。

05 / CALLBACK EDGE

先測 callback，再談完成事件。

目前可驗證的是登入後設定自己的 HTTP(S) callback，並從控制台送出固定的 developer.callback.test。這不是 task completed／failed 的正式投遞。

目前沒有完成事件 worker、事件簽章、重試或 task completion delivery；正式 webhook 需另案核准與實作。

CONTROL PLANE

TEST ONLY

管理你的 key 與 callback

API 文件與 playground查看 request、status、錯誤與可執行範例 API key 控制台建立、查看 prefix、撤銷 secret Callback 設定保存 endpoint，測試 developer.callback.test

文件與 SDK 範例包已在 repo 內；外部 GitHub repository 尚未建立，不用假 URL 取代真實入口。

06 / RESULT SURFACE

結果要能被接住，也要能被誠實描述。

沒有核准的 output fixture，就不把 mock 圖片放進首頁。

OUTPUT / CONTRACT

NO FIXTURE

approved output asset pending

這不是生成結果圖片，只是 output ref 的展示位置。

provider 尚未配置，頁面不冒充成功生成，也不把 `asset://` 或 mock 圖片當成公開成品。

RESPONSE / REDACTED

把結果接進你的產品，而不是接進一個黑盒。

當 provider 可用時，完成 task 會帶回 output ref；目前公開示意只呈現 contract，不宣稱已可產生或交付圖像。

{
  "status": "completed",
  "outputImageRef": "output_…",
  "prompt": "[redacted]",
  "sourceImageRef": "[redacted]",
  "generationParams": "[redacted]"
}

NEXT / ACCESS

先取得入口，再把第一個 task 接起來。

API 文件、SDK 範例包、API key 控制台與 Beta 付款都是目前已核實的下一步。 repository-ready 內容由公司程式碼下載功能取得，再由你發布到自己的 GitHub。

取得／發布 SDK 範例包開啟開發者控制台查看 US$99 Beta 付款

07 / JOIN THE BETA

帶著你的第一個影像 workflow 來。

留下團隊、Email 與使用情境。我們會依目前能力與研究階段確認適合的 Beta 下一步。

不把申請當成自動開通

不對未驗證 provider 流程收費

用真實使用情境決定下一步

APPLICATION / BETA

分享你的使用情境

crebots.com / DEVELOPER BETA

API docs 已上線；外部 GitHub repository 尚未建立

聯絡團隊

圖生圖 REST API，從 task 到結果。