Back to Details

file-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

File Management

文件管理

Overview

概述

Spuree is an agent-friendly cloud storage. Projects contain folders (nestable) and files at any level. This skill manages files — they can live directly under a project or inside any folder. In the API, projects and folders are both called sessions (
sessionType
: 
creative_project
= project, 
session
= folder).
Use this skill when an agent needs to:
  • Search for files and folders by name across all projects
  • Get a file by ID with download URL
  • Upload new files to a project or folder
  • Update file metadata (rename, move) or content (with conflict detection)
  • Delete files (soft delete)
Spuree是一款对Agent友好的云存储服务。项目中包含可嵌套的文件夹和任意层级的文件。本Skill用于管理文件——文件可直接存放在项目下，也可存放在任意文件夹中。在API中，项目和文件夹都被称为sessions（
sessionType
: 
creative_project
= 项目，
session
= 文件夹）。
当Agent需要以下操作时，可使用本Skill：
  • 跨所有项目按名称搜索文件和文件夹
  • 通过ID获取文件及下载URL
  • 上传新文件至项目或文件夹
  • 更新文件元数据（重命名、移动）或内容（含冲突检测）
  • 删除文件（软删除）

Authentication

身份验证

Authorization: Bearer $SPUREE_ACCESS_TOKEN
Or: 
X-API-Key: $SPUREE_API_KEY
. See the authentication skill.
Authorization: Bearer $SPUREE_ACCESS_TOKEN
或者：
X-API-Key: $SPUREE_API_KEY
。请查看身份验证Skill。

Base URLs

基础URL

Base URLEndpoints
https://data.spuree.com/api/v1/files
File CRUD
https://data.spuree.com/api/v1/search
Cross-project search
基础URL端点
https://data.spuree.com/api/v1/files
文件CRUD操作
https://data.spuree.com/api/v1/search
跨项目搜索

Endpoints

端点详情

GET /v1/search

GET /v1/search

Search files and folders by name (case-insensitive substring match). Returns sessions first, then files.
Query Parameters:
ParameterTypeDefaultDescription
q
string—Search query (1–255 chars)
type
string—Filter: 
"file"
or 
"session"
. Omit for both.
workspaceId
string—Restrict results to a specific workspace
limit
integer100Max results (1–100)
Response: 
{ "data": [...], "count": N }
Each result has 
type
(
"file"
or 
"session"
) plus type-specific fields:
  • session: 
    id
    , 
    name
    , 
    sessionType
    , 
    workspaceId
    , 
    createdAt
    , 
    updatedAt
  • file: 
    id
    , 
    fileName
    , 
    fileFormat
    , 
    mimeType
    , 
    size
    , 
    workspaceId
    , 
    sessionId
    , 
    entitySessionId
    , 
    createdAt
    , 
    updatedAt
bash
curl "https://data.spuree.com/api/v1/search?q=hero" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"
按名称搜索文件和文件夹（不区分大小写的子串匹配）。返回结果先显示sessions，再显示文件。
查询参数：
参数类型默认值描述
q
string—搜索关键词（1–255字符）
type
string—过滤条件：
"file"
或
"session"
。留空则返回两者
workspaceId
string—将结果限制在指定工作区
limit
integer100最大返回结果数（1–100）
响应： 
{ "data": [...], "count": N }
每个结果包含
type
（
"file"
或
"session"
）及对应类型的专属字段：
  • session: 
    id
    , 
    name
    , 
    sessionType
    , 
    workspaceId
    , 
    createdAt
    , 
    updatedAt
  • file: 
    id
    , 
    fileName
    , 
    fileFormat
    , 
    mimeType
    , 
    size
    , 
    workspaceId
    , 
    sessionId
    , 
    entitySessionId
    , 
    createdAt
    , 
    updatedAt
bash
curl "https://data.spuree.com/api/v1/search?q=hero" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

GET /v1/files/{fileId}

GET /v1/files/{fileId}

Get file metadata and presigned download URL.
Response: 
{ "data": { id, fileName, fileFormat, mimeType, size, workspaceId, sessionId, entitySessionId, downloadUrl, createdAt, updatedAt } }
bash
curl "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"
获取文件元数据及预签名下载URL。
响应： 
{ "data": { id, fileName, fileFormat, mimeType, size, workspaceId, sessionId, entitySessionId, downloadUrl, createdAt, updatedAt } }
bash
curl "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

POST /v1/files

POST /v1/files

Create a file record and get presigned upload URL(s). Automatically selects upload mode based on file size:
  • < 100 MB → single presigned PUT URL (
    mode: "single"
    )
  • ≥ 100 MB → multipart upload with per-part presigned URLs (
    mode: "multipart"
    )
The caller must then upload to S3 and call 
POST /v1/files/{fileId}/upload/complete
. Without the complete call, the file remains pending and unusable.
Request Body:
FieldTypeRequiredDescription
fileName
stringYesFile name without extension
fileFormat
stringYesExtension in lowercase (e.g., 
fbx
, 
png
)
fileSize
integerYesFile size in bytes (accepts string for backward compat)
sessionId
stringYesTarget project or folder ObjectId
checksum
stringNoCRC32 base64 (8 chars) for end-to-end verification. When provided, the presigned URL is signed with the checksum and S3 verifies the upload matches.
Response (single mode): 
{ messageCode, fileId, mode: "single", uploadUrl, checksumBase64, contentType }
Response (multipart mode): 
{ messageCode, fileId, mode: "multipart", parts: [{partNumber, startByte, endByte, url}, ...], totalParts, expiresAt }
CodeDescription
200Record created, presigned URL(s) returned
404Session not found
409File already exists
bash
curl -X POST "https://data.spuree.com/api/v1/files" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"hero_walk","fileFormat":"fbx","fileSize":5242880,"sessionId":"...","checksum":"AAAAAA=="}'
创建文件记录并获取预签名上传URL。系统会根据文件大小自动选择上传模式：
  • 小于100 MB → 单个预签名PUT URL（
    mode: "single"
    ）
  • 大于等于100 MB → 分块上传，包含各分块的预签名URL（
    mode: "multipart"
    ）
调用方必须先上传文件至S3，再调用
POST /v1/files/{fileId}/upload/complete
。若未调用该完成接口，文件将处于待处理状态，无法使用。
请求体：
字段类型是否必填描述
fileName
string是不含扩展名的文件名
fileFormat
string是小写格式的扩展名（如
fbx
, 
png
）
fileSize
integer是文件大小（字节，为兼容旧版本也接受字符串类型）
sessionId
string是目标项目或文件夹的ObjectId
checksum
string否CRC32 base64格式（8字符），用于端到端验证。提供该值时，预签名URL会附带校验和，S3将验证上传内容是否匹配。
响应（单文件模式）： 
{ messageCode, fileId, mode: "single", uploadUrl, checksumBase64, contentType }
响应（分块模式）： 
{ messageCode, fileId, mode: "multipart", parts: [{partNumber, startByte, endByte, url}, ...], totalParts, expiresAt }
状态码描述
200文件记录创建成功，返回预签名URL
404目标session不存在
409文件已存在
bash
curl -X POST "https://data.spuree.com/api/v1/files" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"hero_walk","fileFormat":"fbx","fileSize":5242880,"sessionId":"...","checksum":"AAAAAA=="}'

POST /v1/files/{fileId}/upload/complete

POST /v1/files/{fileId}/upload/complete

Mark a file upload as completed. Works for both single and multipart uploads — the server auto-detects by checking whether the file has an active multipart 
uploadId
. For multipart, the server calls S3 
ListParts
to collect ETags and then 
CompleteMultipartUpload
.
Request Body:
FieldTypeRequiredDescription
fileId
stringYesMust match path parameter
clientChecksumCRC32
stringNoClient-computed CRC32 for end-to-end verification
Response: 
{ messageCode, fileId, checksum, checksumCRC32 }
  • checksum
    : S3-verified CRC32 (base64) for both single and multipart uploads
  • checksumCRC32
    : S3 FULL_OBJECT CRC32 (multipart only)
bash
curl -X POST "https://data.spuree.com/api/v1/files/{fileId}/upload/complete" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileId": "..."}'
标记文件上传完成。适用于单文件和分块上传——服务器会通过检查文件是否存在活跃的分块
uploadId
自动识别模式。对于分块上传，服务器会调用S3的
ListParts
接口收集ETag，再调用
CompleteMultipartUpload
完成上传。
请求体：
字段类型是否必填描述
fileId
string是必须与路径参数中的fileId一致
clientChecksumCRC32
string否客户端计算的CRC32值，用于端到端验证
响应： 
{ messageCode, fileId, checksum, checksumCRC32 }
  • checksum
    : S3验证后的CRC32值（base64格式），适用于单文件和分块上传
  • checksumCRC32
    : S3返回的完整对象CRC32值（仅分块上传）
bash
curl -X POST "https://data.spuree.com/api/v1/files/{fileId}/upload/complete" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileId": "..."}'

PATCH /v1/files/{fileId}

PATCH /v1/files/{fileId}

Update file metadata. At least one field required.
FieldTypeDescription
fileName
stringNew name (without extension)
fileFormat
stringNew extension (lowercase)
checksum
stringCRC32 base64 (write-once backfill, no edit permission needed)
sessionId
stringMove to target project or folder
Move: Only 
creative_project
(project) and 
session
(folder) targets supported.
Response: 
{ messageCode, fileId }
CodeDescription
200Updated
409Filename conflict in target
bash
curl -X PATCH "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileName": "hero_run_cycle"}'
更新文件元数据。至少需要提供一个字段。
字段类型描述
fileName
string新文件名（不含扩展名）
fileFormat
string新扩展名（小写）
checksum
stringCRC32 base64格式（仅可一次性补填，无需编辑权限）
sessionId
string将文件移动至目标项目或文件夹
移动操作： 仅支持
creative_project
（项目）和
session
（文件夹）作为目标。
响应： 
{ messageCode, fileId }
状态码描述
200更新成功
409目标位置存在同名文件
bash
curl -X PATCH "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileName": "hero_run_cycle"}'

PUT /v1/files/{fileId}

PUT /v1/files/{fileId}

Prepare a content update with optimistic concurrency. Acquires an upload lock. Like 
POST /v1/files
, automatically selects single or multipart mode based on 
fileSize
.
Request Body:
FieldTypeRequiredDescription
expectedChecksum
stringYesCRC32 base64 of current content (for conflict detection)
newChecksum
stringYesCRC32 base64 of new content to upload
fileSize
integerNoSize in bytes. If ≥ 100 MB, returns multipart mode.
Response (single): 
{ messageCode, fileId, mode: "single", uploadUrl, checksumBase64, contentType }
Response (multipart): 
{ messageCode, fileId, mode: "multipart", parts: [{partNumber, startByte, endByte, url}, ...], totalParts, expiresAt }
After receiving the response, upload to S3 then call 
POST /v1/files/{fileId}/upload/complete
.
Upload lock: Single uploads lock for 1 hour. Multipart uploads lock for 6 hours. Same user can re-acquire. Expired locks auto-release.
CodeDescription
200Lock acquired, presigned URL(s) returned
409Checksum mismatch or locked by another user
bash
curl -X PUT "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedChecksum": "a1b2...","newChecksum": "f6e5..."}'
通过乐观锁机制准备内容更新，会获取上传锁。与
POST /v1/files
类似，系统会根据
fileSize
自动选择单文件或分块模式。
请求体：
字段类型是否必填描述
expectedChecksum
string是当前文件内容的CRC32 base64值（用于冲突检测）
newChecksum
string是待上传新内容的CRC32 base64值
fileSize
integer否文件大小（字节）。若大于等于100 MB，返回分块模式
响应（单文件模式）： 
{ messageCode, fileId, mode: "single", uploadUrl, checksumBase64, contentType }
响应（分块模式）： 
{ messageCode, fileId, mode: "multipart", parts: [{partNumber, startByte, endByte, url}, ...], totalParts, expiresAt }
收到响应后，上传文件至S3，再调用
POST /v1/files/{fileId}/upload/complete
。
上传锁： 单文件上传锁有效期1小时，分块上传锁有效期6小时。同一用户可重新获取锁，过期锁会自动释放。
状态码描述
200获取锁成功，返回预签名URL
409校验和不匹配或文件被其他用户锁定
bash
curl -X PUT "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedChecksum": "a1b2...","newChecksum": "f6e5..."}'

GET /v1/files/{fileId}/upload

GET /v1/files/{fileId}/upload

Resume a multipart upload. Returns which parts are already in S3 and fresh presigned URLs for remaining parts.
Query Parameters:
ParameterTypeRequiredDescription
uploadId
stringNoClient's expected uploadId for mismatch detection
checksum
stringNoClient's expected pendingChecksum for conflict detection
Response: 
{ messageCode, fileId, completedParts: [{partNumber, etag, size}, ...], remainingParts: [{partNumber, startByte, endByte, url}, ...], totalParts }
CodeDescription
200Success
400No active multipart upload
409Not in pending status or locked by another user
bash
curl "https://data.spuree.com/api/v1/files/{fileId}/upload" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"
恢复分块上传。返回已上传至S3的分块及剩余分块的新预签名URL。
查询参数：
参数类型是否必填描述
uploadId
string否客户端预期的uploadId，用于检测不匹配情况
checksum
string否客户端预期的pendingChecksum，用于冲突检测
响应： 
{ messageCode, fileId, completedParts: [{partNumber, etag, size}, ...], remainingParts: [{partNumber, startByte, endByte, url}, ...], totalParts }
状态码描述
200操作成功
400无活跃的分块上传任务
409文件未处于待处理状态或被其他用户锁定
bash
curl "https://data.spuree.com/api/v1/files/{fileId}/upload" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

POST /v1/files/{fileId}/upload/urls

POST /v1/files/{fileId}/upload/urls

Refresh presigned URLs for specific parts of a multipart upload. Use when URLs have expired before upload completes.
Request Body: 
{ "partNumbers": [1, 3, 5] }
(1-indexed, min 1 part)
Response: 
{ messageCode, urls: [{partNumber, startByte, endByte, url}, ...] }
CodeDescription
200Success
400No active multipart upload or invalid part numbers
bash
curl -X POST "https://data.spuree.com/api/v1/files/{fileId}/upload/urls" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"partNumbers": [1, 3, 5]}'
刷新分块上传中指定分块的预签名URL。当URL在上传完成前过期时使用。
请求体： 
{ "partNumbers": [1, 3, 5] }
（从1开始索引，至少指定1个分块）
响应： 
{ messageCode, urls: [{partNumber, startByte, endByte, url}, ...] }
状态码描述
200操作成功
400无活跃的分块上传任务或分块编号无效
bash
curl -X POST "https://data.spuree.com/api/v1/files/{fileId}/upload/urls" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"partNumbers": [1, 3, 5]}'

DELETE /v1/files/{fileId}/upload

DELETE /v1/files/{fileId}/upload

Abort a multipart upload. Cleans up S3 parts and marks the file as failed. Idempotent — safe to call on already-aborted uploads.
Response: 
{ messageCode, fileId, message }
CodeDescription
200Aborted
400No active multipart upload
bash
curl -X DELETE "https://data.spuree.com/api/v1/files/{fileId}/upload" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"
终止分块上传。清理S3中的分块并标记文件上传失败。该接口是幂等的——对已终止的上传任务调用也不会报错。
响应： 
{ messageCode, fileId, message }
状态码描述
200终止成功
400无活跃的分块上传任务
bash
curl -X DELETE "https://data.spuree.com/api/v1/files/{fileId}/upload" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

DELETE /v1/files/{fileId}

DELETE /v1/files/{fileId}

Soft-delete a file.
Response: 
{ messageCode, fileId }
bash
curl -X DELETE "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"
软删除文件。
响应： 
{ messageCode, fileId }
bash
curl -X DELETE "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

Common Patterns

常见流程

Single Upload Flow (< 100 MB)

单文件上传流程（小于100 MB）

  1. Compute CRC32 checksum (base64):
    bash
    CHECKSUM=$(python3 -c "import base64, zlib, sys; print(base64.b64encode(zlib.crc32(open('$FILE_PATH','rb').read()).to_bytes(4,'big')).decode())")
  2. Create file record — 
    sessionId
    is the target project or folder:
    POST /v1/files { fileName, fileFormat, fileSize, sessionId, checksum }
→ { fileId, mode: "single", uploadUrl, checksumBase64, contentType }
  3. Upload binary to S3:
    PUT {uploadUrl}
Content-Type: {contentType}
x-amz-checksum-crc32: {checksumBase64}
Body: <file binary>
  4. Complete the upload — REQUIRED (file is not visible until this is called):
    POST /v1/files/{fileId}/upload/complete
Important: All three steps (create → S3 upload → complete) must be performed. Skipping complete leaves the file in a pending state.
  1. 计算CRC32校验和（base64格式）：
    bash
    CHECKSUM=$(python3 -c "import base64, zlib, sys; print(base64.b64encode(zlib.crc32(open('$FILE_PATH','rb').read()).to_bytes(4,'big')).decode())")
  2. 创建文件记录 — 
    sessionId
    为目标项目或文件夹的ID：
    POST /v1/files { fileName, fileFormat, fileSize, sessionId, checksum }
→ { fileId, mode: "single", uploadUrl, checksumBase64, contentType }
  3. 上传二进制文件至S3：
    PUT {uploadUrl}
Content-Type: {contentType}
x-amz-checksum-crc32: {checksumBase64}
Body: <文件二进制内容>
  4. 完成上传——必填（调用此接口前文件不可见）：
    POST /v1/files/{fileId}/upload/complete
重要提示： 必须完成三个步骤（创建→S3上传→完成）。跳过完成步骤会导致文件处于待处理状态。

Multipart Upload Flow (≥ 100 MB)

分块上传流程（大于等于100 MB）

  1. Create file record with 
    fileSize
    ≥ 100 MB:
    POST /v1/files { fileName, fileFormat, fileSize, sessionId, checksum }
→ { fileId, mode: "multipart", parts: [{partNumber, startByte, endByte, url}, ...], totalParts, expiresAt }
  2. Upload each part to its presigned URL:
    PUT {part.url}
Content-Length: {part.endByte - part.startByte + 1}
Body: <file slice from startByte to endByte>
  3. If interrupted, resume with 
    GET /v1/files/{fileId}/upload
    to get completed parts and fresh URLs for remaining parts.
  4. If URLs expire, refresh with 
    POST /v1/files/{fileId}/upload/urls
    for specific parts.
  5. Complete — server auto-detects multipart and calls S3 
    CompleteMultipartUpload
    :
    POST /v1/files/{fileId}/upload/complete
  6. To abort, call 
    DELETE /v1/files/{fileId}/upload
    to clean up S3 parts.
  1. 创建文件记录，且
    fileSize
    大于等于100 MB：
    POST /v1/files { fileName, fileFormat, fileSize, sessionId, checksum }
→ { fileId, mode: "multipart", parts: [{partNumber, startByte, endByte, url}, ...], totalParts, expiresAt }
  2. 上传每个分块至对应的预签名URL：
    PUT {part.url}
Content-Length: {part.endByte - part.startByte + 1}
Body: <文件切片内容，从startByte到endByte>
  3. 若上传中断，调用
    GET /v1/files/{fileId}/upload
    恢复上传，获取已完成分块和剩余分块的新URL。
  4. 若URL过期，调用
    POST /v1/files/{fileId}/upload/urls
    刷新指定分块的URL。
  5. 完成上传——服务器自动识别分块模式并调用S3的
    CompleteMultipartUpload
    接口：
    POST /v1/files/{fileId}/upload/complete
  6. 若需终止上传，调用
    DELETE /v1/files/{fileId}/upload
    清理S3中的分块。

Content Update Flow

内容更新流程

  1. PUT /v1/files/{fileId}
    with checksums (and 
    fileSize
    for multipart) → get upload URL(s)
  2. Upload new content to S3 (single or multipart, same as above)
  3. POST /v1/files/{fileId}/upload/complete
    — REQUIRED
  1. 调用
    PUT /v1/files/{fileId}
    并传入校验和（分块上传需传入
    fileSize
    ）→ 获取上传URL
  2. 将新内容上传至S3（单文件或分块模式，流程同上）
  3. 调用
    POST /v1/files/{fileId}/upload/complete
    ——必填

Viewing / Previewing a File

文件查看/预览

When a user wants to view, preview, or see a file:
  1. If the agent has browser tools (e.g., Chrome DevTools MCP), open the Studio preview URL directly:
    navigate_page → https://studio.spuree.com/file/{fileId}
  2. Otherwise, return the Studio preview URL for the user to click:
    https://studio.spuree.com/file/{fileId}
Do not download the file or attempt to open it locally. The Studio URL is permanent, permission-aware, and renders images, video, 3D, and other supported formats inline in the browser.
Use caseURLProperties
Share with user / preview
https://studio.spuree.com/file/{fileId}
Permanent, permission-aware, renders preview UI
Programmatic download
downloadUrl
from 
GET /v1/files/{fileId}
Short-lived presigned S3 URL — do not share, bypasses permissions and expires
Rule of thumb: after 
POST /v1/files
(upload) or 
GET /v1/search
, build the Studio URL from the returned 
fileId
and return that to the user. Only fetch 
downloadUrl
when the agent itself needs the bytes.
当用户需要查看、预览文件时：
  1. 若Agent具备浏览器工具（如Chrome DevTools MCP），直接打开Studio预览URL：
    navigate_page → https://studio.spuree.com/file/{fileId}
  2. 否则，返回Studio预览URL供用户点击：
    https://studio.spuree.com/file/{fileId}
请勿下载文件或尝试在本地打开。Studio URL是永久链接，具备权限控制功能，可在浏览器中直接渲染图片、视频、3D模型及其他支持的格式。
使用场景URL属性
分享给用户/预览
https://studio.spuree.com/file/{fileId}
永久链接，权限可控，提供预览UI
程序化下载从
GET /v1/files/{fileId}
获取的
downloadUrl
短期有效的S3预签名URL——请勿分享，会绕过权限验证且过期失效
经验法则： 在调用
POST /v1/files
（上传）或
GET /v1/search
后，使用返回的
fileId
构建Studio URL并返回给用户。仅当Agent自身需要文件字节流时，才获取
downloadUrl
。

Search Then Download

搜索后下载

  1. GET /v1/search?q=hero_walk
    → find file ID
  2. GET /v1/files/{fileId}
    → get 
    downloadUrl
  3. Download from the presigned URL
  1. 调用
    GET /v1/search?q=hero_walk
    → 找到文件ID
  2. 调用
    GET /v1/files/{fileId}
    → 获取
    downloadUrl
  3. 从预签名URL下载文件

File Organization

文件组织

Projects and folders are both sessions. 
sessionId
always refers to a session. Session types: 
creative_project
(project), 
session
(folder). Folders nest inside projects or other folders.
S3 key: 
works_{workspaceId}/sess_{sessionId}/file_{fileId}
项目和文件夹都是sessions。
sessionId
始终指向一个session。Session类型：
creative_project
（项目）、
session
（文件夹）。文件夹可嵌套在项目或其他文件夹中。
S3存储路径：
works_{workspaceId}/sess_{sessionId}/file_{fileId}

Studio URLs

Studio URL规则

ResourceURL Pattern
Project
https://studio.spuree.com/projects/{projectId}
Folder (top-level)
https://studio.spuree.com/projects/{projectId}/folders/{folderId}
Folder (nested)
.../folders/{parentId}/{childId}
(up to 5 levels)
File
https://studio.spuree.com/file/{fileId}
资源URL格式
项目
https://studio.spuree.com/projects/{projectId}
文件夹（顶层）
https://studio.spuree.com/projects/{projectId}/folders/{folderId}
文件夹（嵌套）
.../folders/{parentId}/{childId}
（最多支持5层嵌套）
文件
https://studio.spuree.com/file/{fileId}

Error Handling

错误处理

CodeCauseResolution
400Invalid checksum format, missing fields, bad IDFix input format
403No workspace access or edit permissionCheck permissions
404File or session not foundVerify IDs
409 (checksum mismatch)File modified by another userRe-fetch checksum, retry
409 (upload lock)Another user is uploadingWait (lock expires in 1 hour for single, 6 hours for multipart)
409 (filename conflict)Same name exists in targetUse different name or target
401Invalid or expired tokenRefresh via authentication skill
状态码原因解决方案
400校验和格式无效、字段缺失、ID错误修正输入格式
403无工作区访问权限或编辑权限检查权限设置
404文件或session不存在验证ID正确性
409（校验和不匹配）文件被其他用户修改重新获取校验和后重试
409（上传锁）文件被其他用户锁定上传等待（单文件上传锁1小时后过期，分块上传锁6小时后过期）
409（文件名冲突）目标位置存在同名文件使用其他文件名或更换目标位置
401Token无效或过期通过身份验证Skill刷新Token