跳到內容

簽發機械人媒體上傳(beta)

Beta
POST
/v1/robots/raw/media
curl --request POST \
--url https://api.example.yas/v1/robots/raw/media \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "partnerId": "partner", "schemaVersion": "2026-11", "sourceSystem": "partner-export", "robotId": "rbt_example", "recordedAt": "2026-10-15T10:00:00.000Z", "timezone": "Asia/Hong_Kong", "contentType": "text/csv", "byteLength": 1048576 }'

Beta。用 server key 為一個媒體檔簽發網址。請送 partnerId、schemaVersion、sourceSystem、robotId、recordedAt、timezone、contentType 與 byteLength。機械人必須已存在於這個 partner。允許 video/mp4、image/jpeg、image/png、application/json、application/x-ndjson、text/csv、text/plain 與 application/gzip。PUT 請使用宣告的 Content-Type。媒體不接受 application/octet-stream。byteLength 是 1 至 52428800(50 MiB),或較低的 Storage 設定上限。每次簽發都回傳新的 mediaId,不會取代之前的檔案。

上傳憑證有效兩小時,expiresAt 是 ISO-8601 UTC 的憑證期限。須於簽發後 24 小時內 complete。上傳時位元組會先進入私人 Storage,complete 核對長度與類型後才成為 ready。Storage 不會把 signed URL 綁定到 byteLength;長度不符的檔案可能暫存,但不會成為 ready。上傳不可覆寫物件。內容不符時請重新簽發。每個 partner 的地圖與媒體合計最多 10 個未釋放的上傳預留,總額最多 1 GiB。每個預留按 bucket 的實際上限計算;放棄的上傳要等安全清理後才釋放。撤銷 Robots 權限會立即阻擋 mint 與 complete,但已簽發的 Storage 憑證可能仍可用至到期。未完成物件會在上傳憑證與 session 失效後清理;ready 媒體與目前使用中的地圖會保留。

不接受 contentBase64,會回傳 400 invalid_body。請送 byteLength,將位元組上傳到 signed URL,然後呼叫 complete。

Request Bodyrequired

小節:Request Bodyrequired
Media typeapplication/json
object
partnerId
required

合作夥伴 id。必須與 server key 相符。

string
schemaVersion
required

這次內容的 schema 版本。例子:2026-11。

string
sourceSystem
required

送出這次內容的系統名稱。例子:partner-export。

string
robotId
required

機械人 id。這台機械人必須已經存在。

string
recordedAt
required

檔案的錄製時間,ISO-8601。

string format: date-time
timezone
required

IANA 時區。例子:Asia/Hong_Kong。

string
contentType
required

媒體類型。允許 video/mp4、image/jpeg、image/png、application/json、application/x-ndjson、text/csv、text/plain 與 application/gzip。

string
Allowed values: video/mp4 image/jpeg image/png application/json application/x-ndjson text/csv text/plain application/gzip
byteLength
required

實際上傳大小為 1 至 52428800 bytes,並受較低的 Storage 設定上限約束。Complete 時核對。

integer
>= 1 <= 52428800

Example

{
"partnerId": "partner",
"schemaVersion": "2026-11",
"sourceSystem": "partner-export",
"robotId": "rbt_example",
"recordedAt": "2026-10-15T10:00:00.000Z",
"timezone": "Asia/Hong_Kong",
"contentType": "text/csv",
"byteLength": 1048576
}

已簽發上傳網址。Signed URL 有效兩小時,須於簽發後 24 小時內 complete。

Media typeapplication/json
object
mediaId
required

這個檔案的 id。complete 的路徑要用它。再簽發會得到新的 id。

string
uploadUrl
required

在 expiresAt 前把原始位元組 PUT 到此網址。私人物件要 complete 後才成為 ready。請勿分享或記錄此憑證。

string format: uri
objectKey
required

由 YAS 指定。請把位元組送到 uploadUrl。不要自行填這個值。

string
expiresAt
required

上傳憑證的 ISO-8601 UTC 到期時間,為簽發後兩小時。Complete 另有 24 小時期限。

string format: date-time
byteLength
required

宣告的 byteLength。Complete 會拒絕實際大小不符的物件。

integer

Example

{
"mediaId": "62bc5e66-8e11-4940-a70d-22efc1979674",
"uploadUrl": "https://upload.example.yas/media/62bc5e66-8e11-4940-a70d-22efc1979674",
"objectKey": "partners/partner/62bc5e66-8e11-4940-a70d-22efc1979674",
"expiresAt": "2026-10-15T12:00:00.000Z",
"byteLength": 1048576
}
400缺少或錯誤的必填欄位、不支援的 content type,或送了 contentBase64。不會建立上傳。
Media typeapplication/json
object
error
required

穩定的錯誤代碼。沒有 stack trace。

string

Example

{
"error": "invalid_body"
}
401沒有 server key,或 server key 不正確。
Media typeapplication/json
object
error
required

穩定的錯誤代碼。沒有 stack trace。

string

Example

{
"error": "invalid_credentials"
}
403server key 可以只限車輛、只限機械人,或兩者都可以。超出範圍的呼叫是 403 `forbidden`,而且不會保存。`identity_mismatch` 表示 `partnerId` 與 server key 不符。
Media typeapplication/json
object
error
required

穩定的錯誤代碼。沒有 stack trace。

string

Example

{
"error": "forbidden"
}
404未知的 `robotId`。這次什麼都不會存。
Media typeapplication/json
object
error
required

穩定的錯誤代碼。沒有 stack trace。

string

Example

{
"error": "not_found"
}
413宣告大小超過實際 Storage 上限(最多 52428800 bytes)。
Media typeapplication/json
object
error
required

穩定的錯誤代碼。沒有 stack trace。

string

Example

{
"error": "payload_too_large"
}
429未釋放的上傳預留已達 partner 上限。清理釋放容量後再試。
Media typeapplication/json
object
error
required

穩定的錯誤代碼。沒有 stack trace。

string

Example

{
"error": "upload_quota_exceeded"
}
503Storage 或必要設定暫時無法使用。請按 Retry-After 指定時間重試。
Media typeapplication/json
object
error
required

穩定的錯誤代碼。沒有 stack trace。

string

Example

{
"error": "unavailable"
}