把第一個 task 接進你的產品。
這裡是可執行的 REST contract、Node 20 SDK 與 callback test 說明。先用實際 request 驗證你的 key 與輸入，再由你的產品決定輪詢與終態呈現。
01 / CONTRACT
API key → request → task。
先在控制台建立 API key；完整 secret 只在建立成功時顯示一次。所有 image endpoint 都要 使用同一把 key 的 `Authorization: Bearer <api-key>`，合法 body 使用 `sourceImageRef`、`prompt` 與非空 `generationParams`。
| 方法 | 用途 |
|---|---|
| POST /api/image-to-image | 建立 task；provider 可用時回 201 queued |
| GET /api/image-to-image/:taskId | 用同一把 key 讀取自己的 status |
201 response 會提供 `id`、`status: queued` 與同一 task endpoint 的相對 `pollingUrl`；只在收到真實 201 後保存並使用它。
400 · 欄位缺失、空值或無效 JSON
401 · 缺少、錯誤或 revoked Bearer key
404 · unknown、foreign-key 或 legacy task
503 · IMAGE_PROVIDER_NOT_CONFIGURED；502 / 503 · provider unavailable
curl --request POST "$CREBOTS_API_BASE_URL/api/image-to-image" \
--header "Authorization: Bearer $CREBOTS_API_KEY" \
--header "Content-Type: application/json" \
--data-raw '{
"sourceImageRef": "asset://your-provider-accepted-reference",
"prompt": "replace with your image transformation prompt",
"generationParams": {
"provider": "replace-me"
}
}'const apiBaseUrl = process.env.CREBOTS_API_BASE_URL;
const apiKey = process.env.CREBOTS_API_KEY;
if (!apiBaseUrl || !apiKey) throw new Error('Set CREBOTS_API_BASE_URL and CREBOTS_API_KEY first.');
const response = await fetch(`${apiBaseUrl}/api/image-to-image`, {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"sourceImageRef": "asset://your-provider-accepted-reference",
"prompt": "replace with your image transformation prompt",
"generationParams": {
"provider": "replace-me"
}
}),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status} ${result.code ?? 'REQUEST_FAILED'}`);
console.log(result);收到 201 queued 後才會有 task id；目前 provider 未配置，不會產生 polling 範例的假 id。
02 / LIVE REQUEST
用瀏覽器記憶體裡的 key 試一次。
playground 直接呼叫現有 API。key 不寫入資料庫、不放 localStorage，也不會被送到其他 endpoint。
queued：已建立，繼續輪詢。
processing：處理中，繼續輪詢。
completed：停止並讀取 outputImageRef。
failed：停止並讀取 errorMessage。
完整 secret 只存在此分頁的記憶體。
03 / CALLBACK TEST
測試可連線，不把它誤稱為 webhook。
在 callback 控制台保存 HTTP(S) URL，再按測試事件。接收端會收到固定的 `developer.callback.test` shape；它不代表任何 image task 的完成或失敗， 目前也沒有 task completion delivery、簽章或 retry。
目前可用流程是 `GET/PUT /api/callbacks` 保存設定，再以 `POST /api/callbacks/test` 發送測試事件； 未設定回傳 `400 CALLBACK_NOT_CONFIGURED`，不可達或非 2xx 回傳 `502 CALLBACK_DELIVERY_FAILED`。
{
"event": "developer.callback.test",
"id": "00000000-0000-4000-8000-000000000000",
"createdAt": "2026-01-01T00:00:00.000Z",
"data": { "source": "developer-console" }
}04 / BETA LIMITS + REPOSITORY-READY
把範例包帶走，再發布到你的 GitHub。
`developer-kit/` 已包含 README、Quickstart、curl、Node SDK 與 callback receiver。由公司程式碼下載功能取得後， 你可以在自己的 repository 發布；目前沒有已建立的外部 GitHub URL。
- 目前 provider 未配置：合法 request 真實回傳 503，不產生 task。
- 沒有 image upload endpoint；sourceImageRef 必須是既有 reference。
- generationParams 只有非空 JSON object contract，沒有 provider 欄位白名單。
- callback test 不是 completion webhook，沒有 delivery、signature、retry 或 filter。