完整的 SDK 与 API 文档见 Parse API 参考 →

本页讲 REST API 的用法模式：端点总览、请求示例、响应形态，以及 expand 参数的速查。

端点

方法	URL	用途
POST /api/v2/parse	按文件 ID 或 URL 解析（JSON 请求体）
POST /api/v2/parse/upload	一个请求内上传并解析（multipart/form-data）
GET /api/v2/parse	带分页地列举与过滤解析任务
GET /api/v2/parse/{job_id}	查看任务状态并取回结果

**必填请求头：**所有端点都要 Authorization: Bearer YOUR_API_KEY。

可选请求头（Enterprise）：Usage-Tags 把一次请求的用量归属到某个团队、环境或客户，用于账单拆分。见 Usage Tags。

创建解析任务

请求体里带上 file_id（或 source_url）、tier、version 以及其他选项：

终端窗口

curl -X POST 'https://api.cloud.llamaindex.ai/api/v2/parse' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  --data '{
    "file_id": "<file_id>",
    "tier": "agentic",
    "version": "latest"
  }'

创建响应把任务字段放在顶层 —— id、project_id、status 与 tier（这里没有 job 外层）。用顶层的 id 配合 expand 查询参数去取结果（见下文取回结果）。所有可用选项见配置 Parse。

创建响应与取回响应的形态并不相同

POST /api/v2/parse 把 id 与 status 返回在顶层，而 GET /api/v2/parse/{job_id} 把同样的字段嵌在 job 对象之下。轮询时请读 job.status —— 沿用创建响应里那个顶层 .status 路径永远只会读到空值。

page_ranges、crop_box、output_options 这类选项都嵌在同一个 JSON 请求体里 —— 它们不是顶层字段。把 "max_pages": 2 与 file_id/tier/version 平级传会返回 422 extra_forbidden；应当嵌进 page_ranges 之下：

终端窗口

curl -X POST 'https://api.cloud.llamaindex.ai/api/v2/parse' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  --data '{
    "file_id": "<file_id>",
    "tier": "agentic",
    "version": "latest",
    "page_ranges": {"max_pages": 2}
  }'

所有可用选项见配置 Parse。

上传并解析文件

如果你还没有 file_id，POST /api/v2/parse/upload 会在一个 multipart/form-data 请求里同时上传文件并启动解析任务。把文件放在 file 字段、把解析配置作为 configuration 这个 JSON 字符串字段传入：

终端窗口

curl -fL -o report.pdf https://fiscal.treasury.gov/system/files/files/reports-statements/financial-report/2024/executive-summary-2024.pdf

curl -X POST 'https://api.cloud.llamaindex.ai/api/v2/parse/upload' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -F 'file=@report.pdf' \
  -F 'configuration={"tier": "agentic", "version": "latest"}'

与上面的 JSON 创建端点一样，响应在顶层返回 id 与 status。configuration 里能设的全部字段见配置 Parse。

---

列举任务

终端窗口

curl 'https://api.cloud.llamaindex.ai/api/v2/parse?page_size=10&status=COMPLETED' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

查询参数：

参数	类型	说明
page_size	integer	每页最多多少条（可选）
page_token	string	下一页的游标（来自上一次响应）
status	string	过滤条件：PENDING、RUNNING、COMPLETED、FAILED、CANCELLED

响应：

{
  "items": [
    {
      "id": "job-uuid-1",
      "project_id": "project-uuid",
      "status": "COMPLETED",
      "error_message": null
    }
  ],
  "next_page_token": "eyJsYXN0X2lkIjogImpvYi...",
  "total_size": 42
}

---

取回结果

终端窗口

curl 'https://api.cloud.llamaindex.ai/api/v2/parse/{job_id}?expand=markdown,items,metadata' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

响应总是包含一个 job 对象，带 id、project_id、status 与 error_message。其余字段取决于 expand 参数。

expand 取值

取值	返回什么
text	逐页纯文本
markdown	逐页 markdown
items	结构化的 JSON items（逐页的表格、标题、段落）
metadata	页级元数据（置信度、演讲者备注、cost_optimized 等）
job_metadata	任务级的处理详情（耗时、配置回显）
usage	该任务计费的 credit，位于 job.usage 之下
text_full	整份文档作为一个纯文本字符串（所有页拼接）
markdown_full	整份文档作为一个 markdown 字符串（所有页拼接）
text_content_metadata	文本文件的预签名下载地址
markdown_content_metadata	markdown 文件的预签名下载地址
items_content_metadata	items 文件的预签名下载地址
metadata_content_metadata	元数据文件的预签名下载地址
text_full_content_metadata	整份文本文件的预签名下载地址
markdown_full_content_metadata	整份 markdown 文件的预签名下载地址
xlsx_content_metadata	XLSX 文件的预签名下载地址
output_pdf_content_metadata	输出 PDF 的预签名下载地址
images_content_metadata	图片元数据，每张图各自带预签名地址

可以组合多个取值：?expand=markdown,items,images_content_metadata

关于如何选择 expand 取值的详细指引，见取回结果。

usage 的响应形态

expand=usage 会在 job 对象内返回计费的 credit。credits 在计费系统记录该任务之前一直是 null，这可能滞后于任务完成（详情）。

{
  "job": {
    "id": "pjb-123",
    "status": "COMPLETED",
    "usage": {
      "credits": 30.0
    }
  }
}

content metadata 的响应形态

请求 *_content_metadata 这类 expand 取值时，响应会给出可直接下载的预签名 URL：

XLSX 与 PDF：

{
  "result_content_metadata": {
    "xlsx": {
      "size_bytes": 15234,
      "exists": true,
      "presigned_url": "https://s3.amazonaws.com/..."
    },
    "outputPDF": {
      "size_bytes": 102400,
      "exists": true,
      "presigned_url": "https://s3.amazonaws.com/..."
    }
  }
}

图片：

{
  "images_content_metadata": {
    "total_count": 3,
    "images": [
      {
        "index": 0,
        "filename": "image_0.png",
        "content_type": "image/png",
        "size_bytes": 12345,
        "presigned_url": "https://s3.amazonaws.com/..."
      }
    ]
  }
}

你可以用 image_filenames 查询参数过滤图片：

终端窗口

curl 'https://api.cloud.llamaindex.ai/api/v2/parse/{job_id}?expand=images_content_metadata&image_filenames=image_0.png,image_1.jpg' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

**预签名 URL 是临时的。**请在取到后尽快下载，或再次调用端点以换取新地址。

---

错误响应

v2 返回结构化的校验错误：

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["tier"],
      "msg": "Unsupported tier: invalid_tier. Must be one of: fast, cost_effective, agentic, agentic_plus",
      "input": {}
    }
  ]
}

---

另请参阅

• 配置 Parse —— 每个选项的说明与示例
• 取回结果 —— expand 的详细指引与常用模式
• 迁移指南：v1 到 v2 —— 给 v1 用户的参数对照
• 档位 —— 档位对比与版本固定
• Parse API 参考 —— 完整的 SDK 与 API 文档