Skip to main content

创建资源上传会话

创建资源上传会话并获取上传地址，resource_type 指定资源类型，可声明 upload_kind、media_type 和 size_bytes。请求需携带 Idempotency-Key。

  • Scope：admin.v1.resource-uploads.manage
  • 权限项：资源上传管理（resource-uploads）
  • 权限类型：管理
  • 接口：POST/api/openapi/v1/resource-uploads

认证与请求头

使用应用 API Key 调用。当前接口只校验上方独立 Scope；读取、管理与执行权限互不隐含。
名称位置类型必填说明示例
Authorizationheaderstring是应用 API Key，使用 Bearer 方式传递。Bearer qwk_***
X-Request-Idheaderstring否可选的调用追踪标识；未传入时由服务端生成。req-20260831-001

请求参数

名称位置类型必填说明示例
Idempotency-Keyheaderstring必填幂等键，用于避免重复提交"<string>"
media_typebodystring否文件媒体类型"<string>"
resource_typebodystring必填资源类型"skill"
size_bytesbodyinteger · int64否文件大小（字节）1
upload_kindbodystring否上传类型"package"

请求示例

curl --request POST \
  --url 'https://example.invalid/api/openapi/v1/resource-uploads' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Idempotency-Key: <UNIQUE_REQUEST_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "media_type": "<string>",
  "resource_type": "skill",
  "size_bytes": 1,
  "upload_kind": "package"
}'

响应

201 Created

名称类型必填说明示例
asset_urlstring否资源文件地址"<string>"
created_atstring · date-time是创建时间"2026-08-27T10:00:00Z"
error_codestring否错误码"<string>"
expected_sha256string否预期文件 SHA-256 摘要"<string>"
expires_atstring · date-time是到期时间"2026-08-27T10:00:00Z"
max_size_bytesinteger · int64否文件大小上限（字节）0
media_typestring否文件媒体类型"<string>"
resource_typestring是资源类型"skill"
size_bytesinteger · int64否文件大小（字节）0
statusstring是状态"created"
updated_atstring · date-time是更新时间"2026-08-27T10:00:00Z"
upload_headersobject否上传请求头-
upload_idstring · uuid是上传会话 ID"<uuid>"
upload_kindstring是上传类型"package"
upload_methodstring否上传 HTTP 方法"<string>"
upload_urlstring否上传地址"<string>"
upload_url_expires_atstring · date-time否上传地址过期时间"2026-08-27T10:00:00Z"

upload_headers 字段

字段类型必填说明
{key}string否键为上传请求头名称，值为对应请求头值；上传文件时按返回值传递
{
  "asset_url": "<string>",
  "created_at": "2026-08-27T10:00:00Z",
  "error_code": "<string>",
  "expected_sha256": "<string>",
  "expires_at": "2026-08-27T10:00:00Z",
  "max_size_bytes": 0,
  "media_type": "<string>",
  "resource_type": "skill",
  "size_bytes": 0,
  "status": "created",
  "updated_at": "2026-08-27T10:00:00Z",
  "upload_headers": {},
  "upload_id": "<uuid>",
  "upload_kind": "package",
  "upload_method": "<string>",
  "upload_url": "<string>",
  "upload_url_expires_at": "2026-08-27T10:00:00Z"
}

default Flat business error

名称类型必填说明示例
codestring否Stable business error code"<string>"
detailstring是Human-readable error description"<string>"
detailsOpenapiErrorDetails否错误详情-
errorstring是Stable HTTP error type"<string>"

details 字段

字段类型必填说明
fieldstring否校验失败的请求字段
reasonstring否校验失败的原因代码
suggestionstring否建议使用的规范化值
{
  "code": "<string>",
  "detail": "<string>",
  "details": {
    "field": "<string>",
    "reason": "<string>",
    "suggestion": "<string>"
  },
  "error": "<string>"
}