POST/api/public/v1/files/upload-intents

files.upload_intent

所需权限: files:write
类别: 写入
计费: 计入存储空间
幂等: 必须带 Idempotency-Key 请求头；同一个键重试时返回第一次的结果
MCP 工具: 无

参数

Idempotency-Key位置 header必填是类型 string (uuid)

请求体

{
  "type": "object",
  "properties": {
    "filename": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "mime": {
      "type": "string",
      "enum": [
        "application/pdf",
        "application/msword",
        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        "image/png",
        "image/jpeg",
        "image/webp",
        "image/heic",
        "image/heif"
      ]
    },
    "bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 8388608
    },
    "sha256": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "purpose": {
      "type": "string",
      "enum": [
        "grade-sheet",
        "ingestion-source",
        "scheme-source"
      ]
    }
  },
  "required": [
    "filename",
    "mime",
    "bytes",
    "sha256",
    "purpose"
  ],
  "additionalProperties": false
}

成功响应 201

{
  "type": "object",
  "properties": {
    "file": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "purpose": {
          "type": "string",
          "enum": [
            "grade-sheet",
            "ingestion-source",
            "scheme-source"
          ]
        },
        "filename": {
          "type": "string"
        },
        "mime": {
          "type": "string",
          "enum": [
            "application/pdf",
            "application/msword",
            "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
            "image/png",
            "image/jpeg",
            "image/webp",
            "image/heic",
            "image/heif"
          ]
        },
        "bytes": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "sha256": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "state": {
          "type": "string",
          "enum": [
            "pending",
            "verifying",
            "ready",
            "failed",
            "expired"
          ]
        },
        "failureReason": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "file.missing",
                "file.size_mismatch",
                "file.checksum_mismatch",
                "file.type_mismatch"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        },
        "pendingUntil": {
          "type": "string",
          "format": "date-time"
        },
        "verifiedAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "id",
        "purpose",
        "filename",
        "mime",
        "bytes",
        "sha256",
        "state",
        "failureReason",
        "createdAt",
        "pendingUntil",
        "verifiedAt"
      ],
      "additionalProperties": false
    },
    "upload": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "const": "PUT"
            },
            "url": {
              "type": "string",
              "format": "uri"
            },
            "headers": {
              "type": "object",
              "propertyNames": {
                "type": "string"
              },
              "additionalProperties": {
                "type": "string"
              }
            },
            "expiresAt": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": [
            "method",
            "url",
            "headers",
            "expiresAt"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "file",
    "upload"
  ],
  "additionalProperties": false
}

可能返回的错误状态码

400401403404409429500503

所有错误都用同一种错误信封返回，原因码见错误与限流。