提示

多数场景我们建议用 Python 或 TypeScript SDK，而不是直连 REST API。

注意

Enterprise：在 extract 请求上带一个 Usage-Tags 头，就能把抽取用量归属到某个团队、环境或客户。见 Usage Tags。

快速开始

1. 上传文档

用 Upload API 上传文档。本指南用的是 NVIDIA 2025 财年的年报（Form 10-K）：

终端窗口

curl -fL -o nvda_10k.pdf https://cloud.llamaindex.ai/assets/demos/extract/nvda_10k.pdf

curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/files' \
  -H 'Content-Type: multipart/form-data' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -F 'file=@nvda_10k.pdf' \
  -F purpose='extract'

把返回的 id（形如 dfl-xxxxxxxx-...）存下来 —— 下面它就是你的 file_input。

提示

file_input 也接受一个 LlamaParse 任务 ID（pjb-xxxxxxxx-...）。如果你已经用 LlamaParse 解析过该文档，就可以直接把 parse 任务 ID 传进来，跳过重复解析，省下时间与 credit。示例见 SDK 指南 或批量抽取手册。

2. 运行抽取任务

提交抽取任务时把你的 schema 与配置内联传入即可，不必先创建智能体 —— 直接给 data_schema 与选项就行。target_pages 把本任务限定在报告的封面页与财年摘要页，即 130 页中的第 1 页与第 38 页。

终端窗口

curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v2/extract?project_id={PROJECT_ID}' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -d '{
    "file_input": "{FILE_ID}",
    "configuration": {
        "tier": "agentic",
        "version": "2.5",
        "extraction_target": "per_doc",
        "target_pages": "1,38",
        "data_schema": {
            "type": "object",
            "properties": {
                "company_name": {
                    "type": "string",
                    "description": "Name of the company"
                },
                "revenue": {
                    "type": "number",
                    "description": "Annual revenue in USD"
                },
                "fiscal_year": {
                    "type": "integer",
                    "description": "Fiscal year of the report"
                }
            }
        },
        "cite_sources": true,
        "confidence_scores": false,
        "system_prompt": "Focus on the most recent fiscal year if multiple are present"
    }
}'

提示：tier 字段与界面档位一一对应 —— cost_effective 就是 Cost Effective，agentic 就是 Agentic。version 可填形如 2.5 的版本名，或填 latest。见版本。

3. 轮询任务状态

任务是异步处理的。用响应里的任务 id 轮询状态。

终端窗口

curl -X 'GET' \
  'https://api.cloud.llamaindex.ai/api/v2/extract/{JOB_ID}?project_id={PROJECT_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

当 status 为 COMPLETED 时，extract_result 字段就是你的抽取结果。

4. 连同元数据一起取结果

要在响应里带上抽取元数据（引用、置信度得分）与用量统计，请用 expand 参数：

终端窗口

curl -X 'GET' \
  'https://api.cloud.llamaindex.ai/api/v2/extract/{JOB_ID}?project_id={PROJECT_ID}&expand=extract_metadata&expand=usage' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

该端点接受三个 expand 取值，可在同一请求里组合：

取值	增加了什么
extract_metadata	逐字段元数据 —— 引用与置信度得分
configuration	任务实际使用的配置
usage	该任务计费的 credit

5. 查看某任务计费了多少 credit

expand=usage 会返回抽取本身计费的 credit（extract_credits）、产出该文档文本的那个 parse 任务的计费（parse_credits），以及两者之和（credits）：

终端窗口

curl -X 'GET' \
  'https://api.cloud.llamaindex.ai/api/v2/extract/{JOB_ID}?project_id={PROJECT_ID}&expand=usage' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

{
  "id": "ext-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "COMPLETED",
  "usage": {
    "credits": 75.0,
    "extract_credits": 45.0,
    "parse_credits": 30.0
  }
}

一个 parse 任务可以支撑多个抽取任务 —— 比如对同一 file_input 跑两份 schema —— 而它们报告的 parse_credits 是同一个数。要跨任务汇总用量，请累加 extract_credits、并把解析只计一次。

任何分项在计费系统记录之前都会读作 null，这可能晚于任务完成。请再次轮询，而不是把 null 当成零。套餐 credit 与整个组织的用量见计费与用量。

配置选项

configuration 对象支持很多选项，全部配置参数见完整的 API 参考。

遗留的 v1 API

若你必须使用基于智能体的 v1 API，请在侧边栏顶部选择 v1 开关，切到 Extract v1 文档。

完整 API 文档

全部可用端点见完整 API 文档。