Owl3D Cloud API

此 API 可將 2D 影片轉成左右並排 3D。你的程式取得報價、上傳檔案、等待工作完成，再下載結果。轉換方式與 Owl3D Cloud 相同。

AI 程式碼代理可在 /llms.txt 以純文字讀取本頁。

更新日期：2026年11月2日

開始之前

在 app.owl3d.com 登入，並驗證你的電子郵件。
訂閱方案或購買點數。工作會先使用方案的每月點數，再使用已購買的點數。試用點數也可以使用。
開啟 API 金鑰頁面並建立金鑰。頁面只會顯示金鑰一次。

將金鑰放在環境變數 OWL3D_API_KEY。本頁所有範例都從這裡讀取金鑰。

使用 API 須遵守 Owl3D Cloud API Terms（英文）。

Shell

export OWL3D_API_KEY="o3d_live_..."

驗證

項目	值
Base URL	`https://api.owl3d.com`
金鑰格式	`o3d_live_<keyId>_<secret>`
驗證標頭	`Authorization: Bearer <key>`

Bearer 的 B 要大寫，後面接一個空格。其他寫法會得到 401。

每個路由都需要一個範圍：jobs:read 或 jobs:write。路由表列出每個路由的範圍。

請保密金鑰。金鑰可以花掉你的點數。金鑰外洩時，請在 API 金鑰頁面撤銷。撤銷的金鑰會在 60 秒內失效。

GET /v1/jobs/{id}

curl

curl https://api.owl3d.com/v1/jobs/job_... \
  -H "Authorization: Bearer $OWL3D_API_KEY"

回應200

{"id": "job_...", "status": "converting"}

轉換一支影片

下載一個腳本，對你的影片執行。每個腳本都會完成下列所有步驟。

腳本	需求	執行
convert.sh	bash, curl, jq, ffprobe	`bash convert.sh my-video.mp4`
convert.py	Python 3.9+, `requests`, ffprobe	`python3 convert.py my-video.mp4`
convert.mjs	Node.js 20+, ffprobe	`node convert.mjs my-video.mp4`

convert.sh · convert.py · convert.mjs

curl

curl -O https://www.owl3d.com/docs/api/convert.sh
bash convert.sh my-video.mp4

腳本是選用的。你自己的程式可以用任何語言。它只需要 HTTPS 呼叫、SHA-256 和檔案資訊。使用先上傳時，只需要 HTTPS 呼叫。

流程共六步：

讀取檔案資訊並產生指紋。
POST /v1/estimates：取得報價。不會扣款。
POST /v1/jobs：同意報價。這會保留點數。
將每個分段 PUT 到它的上傳 URL，然後 POST /v1/jobs/{id}/upload-complete。
每 15 秒輪詢 GET /v1/jobs/{id}。
GET /v1/jobs/{id}/result：取得下載連結。連結有效 15 分鐘，且只能用 GET。

先上傳會略過第 1 步和第 2 步。你的程式把檔名和檔案大小送到 POST /v1/jobs。上傳後，伺服器讀取檔案並決定價格。

錯誤

大多數錯誤回應的內容是 JSON，其中 error 是簡短的代碼。

狀態	意義
`400`	請求錯誤，例如 `bad_fingerprint`
`401`	沒有 token、token 錯誤，或金鑰已撤銷
`402`	`short_of_credits`：方案點數、試用點數和已購買點數合計仍不足以支付價格
`403`	`insufficient_scope`，或該路由未公開
`404`	`no_job`。在 Cloud app 建立的工作，API 看不到
`409`	狀態衝突，例如 `not_uploading` 或 `endpoint_exists`
`410`	輸出已過期，或 `insufficient_credits_expired`：工作等點數已滿 24 小時
`429`	某個上限已滿。請見限制

重試規則：

收到 429 時，等待 Retry-After 秒，再送出相同的請求。
收到 5xx 或網路錯誤時，以退避方式重試，間隔從 1 秒增加到 60 秒。
收到其他 4xx 時，請修正請求。

curl

curl -i https://api.owl3d.com/v1/jobs/job_unknown \
  -H "Authorization: Bearer $OWL3D_API_KEY"

回應404

{"error": "no_job"}

限制

限制	值	回應
進行中的工作	帳號的所有 API 金鑰合計 10 個。帳號所有管道合計 15 個。每個金鑰可另設上限	`429 concurrency_limit`、`Retry-After: 15`
請求	每個金鑰每分鐘 120 次	`429`、`Retry-After: 60`
突發	每個路由每秒 10 次，突發 20 次，所有呼叫端合計	`429 throttled`、`Retry-After: 1`
每日點數上限	每個金鑰可選	`429 daily_credit_cap`，直到 00:00 UTC
啟用中的金鑰	每個帳號 10 把	拒絕建立
輸入	100 GB、3 小時、4096 x 2160、60 fps	報價被拒絕
容器格式	MP4, MOV, MKV, M4V	報價被拒絕

429 concurrency_limit 的回應內容會寫出已滿的上限。scope 為 api（帳號的所有 API 金鑰）、account（帳號的所有工作）或 key（此金鑰）。等一個工作結束後，再開始下一個。

回應429

{
  "error": "concurrency_limit",
  "scope": "api",
  "limit": 10,
  "inProgress": 10
}

價格

付款前，POST /v1/estimates 會給出檔案的確切價格。

兩種方式都一樣：伺服器讀取上傳的檔案，並依檔案決定最終價格。使用先上傳時，上傳後才看得到價格。餘額不足以支付價格時，工作會等待。請見點數不足。

路由

方法與路徑	範圍	用途
`POST /v1/estimates`	`jobs:write`	報價與預估時間。不會扣款。有效 1 小時，僅限一個工作
`POST /v1/jobs`	`jobs:write`	保留點數並回傳上傳計畫。帶 `estimateId`，或帶 `filename` 和 `sizeBytes`（先上傳）
`GET /v1/jobs/{id}/upload`	`jobs:read`	上傳狀態：`done`、`missing` 和新的 `parts` URL
`POST /v1/jobs/{id}/upload-complete`	`jobs:write`	送出 ETag 並將工作排入佇列
`GET /v1/jobs/{id}`	`jobs:read`	狀態、進度、剩餘時間
`POST /v1/jobs/{id}/cancel`	`jobs:write`	取消工作
`POST /v1/jobs/{id}/resume`	`jobs:write`	補點數後，繼續 `insufficient_credits` 的工作。不必重新上傳
`GET /v1/jobs/{id}/result`	`jobs:read`	下載連結，15 分鐘

報價

POST /v1/estimates 提供一個檔案的價格和時間。不會扣款。報價有效 1 小時，僅限一個工作。

欄位	值
`name`、`size`	檔案名稱，以及以位元組計的大小
`durationSeconds`、`width`、`height`、`fps`	用任何工具從檔案讀取，例如 ffprobe 或 MediaInfo
`codec`	`H.264`、`HEVC`、`AV1`、`VP9` 其中之一
`bitDepth`、`chroma`	從檔案讀取。`chroma` 為 `4:2:0`
`fingerprint`	`{size, headSha256, tailSha256, edgeBytes}`

edgeBytes 為 4194304；檔案較小時，則為檔案大小。
headSha256 和 tailSha256 是檔案前 edgeBytes 位元組與最後 edgeBytes 位元組的雜湊。

回應中的 "ok": false 表示報價被拒絕。請讀取 reason。credits.shortBy 大於 0 表示帳號需要更多點數。credits.fromPlan、credits.fromTrial 和 credits.fromPurchased 表示由哪些點數支付價格。

POST /v1/estimates

curl

curl https://api.owl3d.com/v1/estimates \
  -H "Authorization: Bearer $OWL3D_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-video.mp4",
    "size": 104857600,
    "durationSeconds": 120,
    "width": 1920, "height": 1080, "fps": 24,
    "codec": "H.264", "bitDepth": 8, "chroma": "4:2:0",
    "fingerprint": {
      "size": 104857600,
      "headSha256": "<SHA-256 of the first 4194304 bytes>",
      "tailSha256": "<SHA-256 of the last 4194304 bytes>",
      "edgeBytes": 4194304
    }
  }'

回應200

{
  "ok": true,
  "id": "est_...",
  "credits": {
    "total": 60,
    "fromPlan": 60,
    "fromTrial": 0,
    "fromPurchased": 0,
    "shortBy": 0
  },
  "etaMinutes": 6,
  "hdr": {"detected": false},
  "output": {"format": "FULL_SBS", "width": 3840, "height": 1080}
}

工作

以 {"estimateId": "est_..."} 呼叫 POST /v1/jobs，即同意報價。這會保留點數。回應含工作的 id 和上傳計畫：upload.partSize 和 upload.parts 的 URL。

輸出選項

POST /v1/jobs 也接受 output: {layout, max_height}。

layout：full_sbs（預設）。
max_height："source"（預設）、2160 或 1080。

POST /v1/jobs

curl

curl https://api.owl3d.com/v1/jobs \
  -H "Authorization: Bearer $OWL3D_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"estimateId": "est_...", "output": {"layout": "full_sbs", "max_height": "source"}}'

回應201

{
  "id": "job_...",
  "status": "uploading",
  "upload": {
    "partSize": 67108864,
    "parts": ["https://...", "https://..."],
    "completeUrl": "/v1/jobs/job_.../upload-complete"
  }
}

先上傳

送出 POST /v1/jobs 時不帶 estimateId。你的程式不用讀取檔案，也不用產生指紋。

欄位	值
`filename`	檔名，最多 255 個字元。結尾是 `.mp4`、`.mov`、`.mkv` 或 `.m4v`
`sizeBytes`	檔案大小，以位元組計
`output`	選用。請見輸出選項

餘額必須足以支付最低價格。否則回應是 402 short_of_credits，也不會建立工作。
201 回應另外有 reservedCredits 和 "priceAfterUpload": true。
上傳後，伺服器讀取檔案並決定價格。
如果伺服器無法轉換這個檔案，工作會變成 failed。不會扣款，檔案也會刪除。

HDR10 影片需要報價。沒有報價時，回應是 400 hdr_needs_estimate。

POST /v1/jobs (upload first)

curl

curl https://api.owl3d.com/v1/jobs \
  -H "Authorization: Bearer $OWL3D_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"filename\": \"my-video.mp4\", \"sizeBytes\": $(wc -c < my-video.mp4)}"

回應201

{
  "id": "job_...",
  "status": "uploading",
  "upload": {
    "partSize": 67108864,
    "parts": ["https://...", "https://..."],
    "completeUrl": "/v1/jobs/job_.../upload-complete"
  },
  "reservedCredits": 15,
  "priceAfterUpload": true
}

點數不足

價格高於餘額時，工作會變成 insufficient_credits。不會扣款。有報價和沒有報價的工作都一樣。

GET /v1/jobs/{id} 會顯示 shortBy（要補的點數）、neededCredits、deleteAt 和 resumeUrl。
補點數後，送出 POST /v1/jobs/{id}/resume。不要重新上傳檔案。
餘額仍不足時，resume 回應 402 short_of_credits 並附上 shortBy。
在 deleteAt（24 小時）前沒有 resume，工作會變成 failed，代碼是 insufficient_credits_expired。檔案會刪除。

POST /v1/jobs/{id}/resume

curl

curl -X POST https://api.owl3d.com/v1/jobs/job_.../resume \
  -H "Authorization: Bearer $OWL3D_API_KEY"

回應200

{
  "id": "job_...",
  "status": "queued"
}

回應402

{
  "error": "short_of_credits",
  "shortBy": 120,
  "neededCredits": 450,
  "deleteAt": "2026-11-04T09:00:00.000Z"
}

上傳

將檔案切成每段 upload.partSize 位元組的分段。第 1 段從位元組 0 開始。
將每個分段 PUT 到 upload.parts 中對應的 URL。保留每個回應的 ETag 標頭，連同引號。
以 {"etags": [...]} 呼叫 POST /v1/jobs/{id}/upload-complete，ETag 依分段順序排列。

每個 URL 只簽署一個固定長度。每段必須是 partSize 位元組，最後一段放剩下的部分。長度不符或使用 chunked 內容時，儲存服務會回應 403。請送出 Content-Length。

上傳中斷時，不要重新開始：

呼叫 GET /v1/jobs/{id}/upload。
讀取 done。每個項目含 partNumber、etag 和 size。
讀取 missing。它列出分段編號。
將每個缺少的分段上傳到 parts[partNumber - 1]。這些 URL 有效 1 小時。
依分段順序帶入所有 ETag 完成上傳。使用同一個檔案。

請在 24 小時內完成上傳。超過時間後，儲存空間會移除未完成上傳的分段。

PUT upload.parts[n] · POST /v1/jobs/{id}/upload-complete

curl

split -b 67108864 my-video.mp4 part_
curl -sS -D - -o /dev/null -X PUT --upload-file part_aa "<upload.parts[0]>" | grep -i '^etag'
curl -sS -D - -o /dev/null -X PUT --upload-file part_ab "<upload.parts[1]>" | grep -i '^etag'

curl https://api.owl3d.com/v1/jobs/job_.../upload-complete \
  -H "Authorization: Bearer $OWL3D_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"etags": ["\"<etag of part 1>\"", "\"<etag of part 2>\""]}'

回應200

{"id": "job_...", "status": "queued"}

GET /v1/jobs/{id}/upload

curl

curl https://api.owl3d.com/v1/jobs/job_.../upload \
  -H "Authorization: Bearer $OWL3D_API_KEY"

回應200

{
  "id": "job_...",
  "partSize": 67108864,
  "parts": ["https://...", "https://..."],
  "completeUrl": "/v1/jobs/job_.../upload-complete",
  "done": [{"partNumber": 1, "etag": "\"...\"", "size": 67108864}],
  "missing": [2]
}

工作狀態

GET /v1/jobs/{id} 提供狀態、進度和剩餘時間。每 15 秒輪詢一次。

`status`	意義
`uploading`	工作在等待檔案
`queued`	工作在等待 GPU。工作可能短暫地從 `converting` 回到 `queued`
`converting`	`progress` 從 0 到 1
`delayed`	由我們這邊暫緩。點數仍保留
`insufficient_credits`	價格高於餘額。補 `shortBy` 點後再 resume。請見點數不足
`done`	完成。`result` 含名稱、大小和連結路徑
`failed`	`error` 含 `code`。點數已退回
`cancelled`	已被呼叫端取消

GET /v1/jobs/{id}

curl

curl https://api.owl3d.com/v1/jobs/job_... \
  -H "Authorization: Bearer $OWL3D_API_KEY"

回應200

{
  "id": "job_...",
  "status": "converting",
  "progress": 0.42,
  "etaSeconds": 310
}

結果

GET /v1/jobs/{id}/result 為 done 的工作提供下載連結。連結有效 15 分鐘，且只能用 GET。要新的連結時，再呼叫一次此路由。輸出已過期時，回應為 410。

GET /v1/jobs/{id}/result

curl

curl https://api.owl3d.com/v1/jobs/job_.../result \
  -H "Authorization: Bearer $OWL3D_API_KEY"
curl -o output.mp4 "<url>"

回應200

{
  "url": "https://...",
  "filename": "...",
  "sizeBytes": 209715200,
  "expiresInS": 900
}

取消

POST /v1/jobs/{id}/cancel 會取消工作。轉換開始前取消的工作不收費。開始後取消，費用為報價 x progress，無條件進位，至少 1 點。

POST /v1/jobs/{id}/cancel

curl

curl -X POST https://api.owl3d.com/v1/jobs/job_.../cancel \
  -H "Authorization: Bearer $OWL3D_API_KEY"

回應200

{"id": "job_...", "status": "cancelled"}