# 查詢素材 Canonical URL: https://sosoapi.ai/zh-hant/docs/api/assets-api-list Contract: sha256:563d2d581da0ad29 明確傳 workspace_id，按 asset_type、source 或 tag 查素材；回傳分頁及總數，limit 最大 100，配合 offset。 POST /assets-api/list ## 驗證及權限 - **接受嘅憑證類型:** user_session, delegated_oauth, personal_access_token - **委派權限:** agent:operate - **最低工作空間角色:** viewer - **存取範圍:** 已登入使用者及獲授權資源範圍 - **需要所有工作空間同意:** 唔係 - **會改動狀態:** 唔係 - **完成依據:** synchronous_http_response 憑證唔能夠擴大持有人權限。實際操作仍會檢查工作空間成員資格、資源擁有權、已選工作空間及能力授權。Tool profile 只改變可見工具，唔會授權。 ## 請求欄位 ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "asset_type": { "anyOf": [ { "type": "string", "enum": [ "text", "image", "video", "audio" ] }, { "type": "array", "items": { "type": "string", "enum": [ "text", "image", "video", "audio" ] } } ] }, "source": { "type": "string", "maxLength": 64 }, "tag": { "type": "string", "maxLength": 64 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "description": "Rows to skip. Served up to 100000; beyond it 400 OFFSET_TOO_LARGE. Prefer filters to paging deep.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "include_version": { "description": "Optional. true adds the resource version to the answer.", "type": "boolean" } }, "additionalProperties": false } ``` ## 回應及完成條件 成功 HTTP 狀態碼: 200 HTTP 成功只表示呢次操作嘅回應。背景工作要保留回傳 ID，讀取同一操作直到文件指定嘅終態。接受請求、排程成功或客戶端逾時，都唔代表已發佈。 ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "string" } ] }, "workspace_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "user_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "asset_type": { "type": "string", "enum": [ "text", "image", "video", "audio" ] }, "asset_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preview_url": { "description": "Workspace-authorized temporary read URL. Refresh through Asset read/list after preview_expires_at; keep asset_url as persisted media identity.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "preview_expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "created_at": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "workspace_id", "user_id", "asset_type", "asset_url", "title", "description", "tags", "metadata", "created_at" ] } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "assets", "total" ] } ``` ## 錯誤及安全重試 檢查 HTTP 狀態及實際回應格式。驗證400可能回傳 ZodError；handler 錯誤可能係 error／message／code envelope。保留可用嘅 request_id 或 x-request-id，唔好記錄憑證。401／403先修正存取問題；429遵守 Retry-After。寫入結果未明或5xx時，先讀原有結果，再決定重試；只喺操作支援時重用 idempotency key，並冇通用重試或 exactly-once 保證。 ## 範例 以下虛構值已按 contract 驗證，唔係真實帳戶 ID、憑證或發佈紀錄。請用已授權範圍回傳嘅 ID、已準備好嘅素材及已審核排程取代，寫入前核對平台資格。此頁唔會呼叫 API。 喺伺服器環境設定 SOSOAPI_ACCESS_TOKEN，使用此操作接受嘅憑證。唔好放入瀏覽器程式。一般 agent 建議透過 sosoapi auth login 用瀏覽器 OAuth，由 CLI 管理憑證更新。 request.json ```json {} ``` cURL ```bash curl --request POST \ "https://gqeshlawtcexsapabaui.supabase.co/functions/v1/assets-api/list" \ -H "Authorization: Bearer $SOSOAPI_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ --data-binary @request.json ``` JavaScript ```js // Server-side JavaScript. Do not print tokens or credential-bearing responses. const token = process.env.SOSOAPI_ACCESS_TOKEN; if (!token) throw new Error("Set an accepted credential for this operation"); const response = await fetch("https://gqeshlawtcexsapabaui.supabase.co/functions/v1/assets-api/list", { method: "POST", headers: { "Content-Type": "application/json", Authorization: "Bearer " + token }, body: JSON.stringify({}) }); const result = await response.json(); // Check response.ok, the operation-specific body and completion state before continuing. ``` CLI ```bash npx sosoapi api post /assets-api/list < request.json ``` 虛構回應範例 ```json { "assets": [], "total": 0 } ``` ## 相關工具及指南 MCP: sosoapi_query_assets [API reference](https://sosoapi.ai/zh-hant/docs/api)