> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dropcv.work/llms.txt
> Use this file to discover all available pages before exploring further.

# 文件上传

> save_candidate 调用前的附件上传流程。

`save_candidate` 需要附件（简历 PDF / 截图）。文件不能直接走 skill JSON 调用，要先通过独立 multipart 端点上传，拿到 `file_id` 后再传给 `save_candidate`。

<Note>
  文件上传需要 key 的 **write 权限**（同写 skill 一致）。
</Note>

## 端点

```
POST /api/external/v1/files/upload
Content-Type: multipart/form-data
```

## 字段

| 字段                  | 类型          | 说明                                             |
| ------------------- | ----------- | ---------------------------------------------- |
| `file`              | file        | 文件本体                                           |
| `mime_type`         | string      | `image/jpeg` / `image/png` / `application/pdf` |
| `original_filename` | string (可选) | 原始文件名，用于显示                                     |

## 限制

* 单文件 ≤ **10 MB**
* 仅支持 `image/jpeg` / `image/png` / `application/pdf`
* 24 小时未被 `save_candidate` 等写 skill 消费的文件会被清理；**消费后永久持有**

## 示例

```bash theme={null}
curl -X POST https://api.dropcv.work/api/external/v1/files/upload \
  -H "Authorization: Bearer $DROPCV_API_KEY" \
  -F "file=@resume.pdf" \
  -F "mime_type=application/pdf" \
  -F "original_filename=张三-简历.pdf"
```

返回：

```json theme={null}
{
  "file_id": "f_01HXXXXXXX...",
  "expires_at": "2026-05-13T12:00:00Z",
  "size_bytes": 234567
}
```

## 完整流程：把 PDF 简历入库

```bash theme={null}
# 1. 上传文件
FILE_ID=$(curl -s -X POST https://api.dropcv.work/api/external/v1/files/upload \
  -H "Authorization: Bearer $DROPCV_API_KEY" \
  -F "file=@resume.pdf" \
  -F "mime_type=application/pdf" \
  | jq -r .file_id)

# 2. 调用 save_candidate
curl -X POST https://api.dropcv.work/api/external/v1/skills/save_candidate/invoke \
  -H "Authorization: Bearer $DROPCV_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"params\": {
      \"candidate_profile_text\": \"姓名：张三\\n职位：高级后端\\n...\",
      \"attachment_file_id\": \"$FILE_ID\"
    }
  }"
```