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

# PDF Inputs

> How to send PDFs to OpenRouter models

OpenRouter supports PDF processing through the [Responses API](https://openrouter.ai/docs/api_reference/responses/overview.md) (`/api/v1/responses`) and Chat Completions (`/api/v1/chat/completions`). On the Responses API, PDFs can be sent as **direct URLs** (`file_url`) or **base64-encoded data URLs** (`file_data`) in the `input` array, via the `input_file` content type; on Chat Completions they go in a `file` content part. This feature works on **any** model on OpenRouter. The examples on this page use the Responses API except where noted.

**URL support**: Send publicly accessible PDFs directly without downloading or encoding **Base64 support**: Required for local files or private documents that aren't publicly accessible

PDFs also work in the chat room for interactive testing.

> [!NOTE]
>
> When a model supports file input natively, the PDF is passed directly to the model. When the model does not support file input natively, OpenRouter will parse the file and pass the parsed results to the requested model.

> [!TIP]
>
> You can send both PDFs and other file types in the same request.

## Plugin Configuration

To configure PDF processing, use the `plugins` parameter in your request. OpenRouter provides several PDF processing engines with different capabilities and pricing; `engine` is one of `cloudflare-ai`, `mistral-ocr`, or `native`:

```json lines theme={null}
{
  "plugins": [
    {
      "id": "file-parser",
      "pdf": {
        "engine": "cloudflare-ai"
      }
    }
  ]
}
```

## Pricing

OpenRouter provides several PDF processing engines:

1. `"mistral-ocr"`: Best for scanned documents or PDFs with images (\$2 per 1,000 pages). Requests pinned to the US data region use Mistral's US regional endpoint and the US rate (\$2.2 per 1,000 pages), which includes Mistral's 10% regional upcharge.
2. `"cloudflare-ai"`: Converts PDFs to markdown using Cloudflare Workers AI (Free).
3. `"native"`: Only available for models that support file input natively (charged as input tokens).

> [!NOTE]
>
> The `"pdf-text"` engine is deprecated and automatically redirected to `"cloudflare-ai"`. Existing requests using `"pdf-text"` will continue to work.

> [!WARNING]
>
> OCR costs apply to all requests, including BYOK. OpenRouter uses its own Mistral key for OCR (not your BYOK key), so the per-page fee is always billed to your OpenRouter account.

If you don't explicitly specify an engine, OpenRouter will default first to the model's native file processing capabilities, and if that's not available, we will use the `"mistral-ocr"` engine.

## OCR Image Limits

When the `"mistral-ocr"` engine extracts images from a PDF, OpenRouter requests at most **8 images per PDF** from Mistral via the OCR API's `image_limit` parameter, and forwards no more than 8 images per request to the downstream model. Surplus images are dropped while all extracted text is preserved in full.

This cap exists because per-prompt image limits vary significantly across providers. Some reject requests with more than 8 images outright, and even providers with higher caps often fail with context-length errors when a long PDF emits one image per page. Capping at 8 keeps requests within the limits of every supported provider.

If your downstream model does not accept image input at all, OCR-extracted images are stripped entirely and only the parsed text is forwarded.

## Using PDF URLs

For publicly accessible PDFs, you can send the URL directly without needing to download and encode the file:

```typescript title="TypeScript SDK" expandable lines theme={null}
import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const result = await openRouter.responses.send({
  responsesRequest: {
    model: '~anthropic/claude-sonnet-latest',
    input: [
      {
        role: 'user',
        content: [
          {
            type: 'input_text',
            text: 'What are the main points in this document?',
          },
          {
            type: 'input_file',
            filename: 'document.pdf',
            fileUrl: 'https://bitcoin.org/bitcoin.pdf',
          },
        ],
      },
    ],
    // Optional: Configure PDF processing engine
    plugins: [
      {
        id: 'file-parser',
        pdf: {
          engine: 'mistral-ocr',
        },
      },
    ],
    stream: false,
  },
});

console.log(result);
```

```python Python expandable lines theme={null}
import requests
import json
import os

url = "https://openrouter.ai/api/v1/responses"
headers = {
    "Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
    "Content-Type": "application/json"
}

input_items = [
    {
        "role": "user",
        "content": [
            {
                "type": "input_text",
                "text": "What are the main points in this document?"
            },
            {
                "type": "input_file",
                "filename": "document.pdf",
                "file_url": "https://bitcoin.org/bitcoin.pdf"
            },
        ]
    }
]

# Optional: Configure PDF processing engine
plugins = [
    {
        "id": "file-parser",
        "pdf": {
            "engine": "mistral-ocr"
        }
    }
]

payload = {
    "model": "~anthropic/claude-sonnet-latest",
    "input": input_items,
    "plugins": plugins
}

response = requests.post(url, headers=headers, json=payload)
print(json.dumps(response.json(), indent=2))

```

```typescript title="TypeScript (fetch)" expandable lines theme={null}
const response = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: '~anthropic/claude-sonnet-latest',
    input: [
      {
        role: 'user' as const,
        content: [
          {
            type: 'input_text',
            text: 'What are the main points in this document?',
          },
          {
            type: 'input_file',
            filename: 'document.pdf',
            file_url: 'https://bitcoin.org/bitcoin.pdf',
          },
        ],
      },
    ],
    // Optional: Configure PDF processing engine
    plugins: [
      {
        id: 'file-parser',
        pdf: {
          engine: 'mistral-ocr',
        },
      },
    ],
  }),
});

const data = await response.json();
console.log(data);
```

```go title="Go" lines theme={null}
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"model": "~anthropic/claude-sonnet-latest",
		"input": []any{
			map[string]any{
				"role": "user",
				"content": []any{
					map[string]any{
						"type": "input_text",
						"text": "What are the main points in this document?",
					},
					map[string]any{
						"type":     "input_file",
						"filename": "document.pdf",
						"file_url": "https://bitcoin.org/bitcoin.pdf",
					},
				},
			},
		},
		// Optional: Configure PDF processing engine
		"plugins": []any{
			map[string]any{
				"id":  "file-parser",
				"pdf": map[string]any{"engine": "mistral-ocr"},
			},
		},
		"stream": false,
	})

	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/responses", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	out, _ := io.ReadAll(resp.Body)
	if resp.StatusCode != http.StatusOK {
		log.Fatalf("status %d: %s", resp.StatusCode, out)
	}
	fmt.Println(string(out))
}

```

```bash title="cURL" lines theme={null}
curl https://openrouter.ai/api/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d '{
  "model": "~anthropic/claude-sonnet-latest",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "What are the main points in this document?"
        },
        {
          "type": "input_file",
          "filename": "document.pdf",
          "file_url": "https://bitcoin.org/bitcoin.pdf"
        }
      ]
    }
  ],
  "plugins": [
    {
      "id": "file-parser",
      "pdf": {
        "engine": "mistral-ocr"
      }
    }
  ],
  "stream": false
}'
```

```text title="Output" theme={null}
{
  background: false,
  completedAt: 1794950420,
  createdAt: 1794950407,
  error: null,
  frequencyPenalty: 0,
  id: "gen-1794950407-QkyXb6KOcBGzO6O0sRdj",
  incompleteDetails: null,
  instructions: null,
  maxOutputTokens: null,
  maxToolCalls: null,
  metadata: {},
  model: "anthropic/claude-sonnet-5.5",
  object: "response",
  output: [
    {
      content: [Array ...],
      id: "msg_tmp_uyrfeyzgm3q",
      role: "assistant",
      status: "completed",
      type: "message",
    }
  ],
  parallelToolCalls: true,
  presencePenalty: 0,
  previousResponseId: null,
  promptCacheKey: null,
  promptCacheOptions: null,
  reasoning: {
    effort: "high",
  },
  safetyIdentifier: null,
  serviceTier: "default",
  status: "completed",
  store: false,
  temperature: 1,
  text: {
    format: {
      type: "text",
    },
```

> [!NOTE]
>
> PDF URLs work with all processing engines. For Mistral OCR, the URL is passed directly to the service. For other engines, OpenRouter fetches the PDF and processes it internally.

## Using Base64 Encoded PDFs

For local PDF files or when you need to send PDF content directly, you can base64 encode the file:

```python Python expandable lines theme={null}
import requests
import json
import base64
import os
from pathlib import Path

def encode_pdf_to_base64(pdf_path):
    with open(pdf_path, "rb") as pdf_file:
        return base64.b64encode(pdf_file.read()).decode('utf-8')

url = "https://openrouter.ai/api/v1/responses"
headers = {
    "Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
    "Content-Type": "application/json"
}

# Read and encode the PDF
pdf_path = "path/to/your/document.pdf"
base64_pdf = encode_pdf_to_base64(pdf_path)
data_url = f"data:application/pdf;base64,{base64_pdf}"

input_items = [
    {
        "role": "user",
        "content": [
            {
                "type": "input_text",
                "text": "What are the main points in this document?"
            },
            {
                "type": "input_file",
                "filename": "document.pdf",
                "file_data": data_url
            },
        ]
    }
]

# Optional: Configure PDF processing engine
# PDF parsing will still work even if the plugin is not explicitly set
plugins = [
    {
        "id": "file-parser",
        "pdf": {
            "engine": "cloudflare-ai"  # defaults to "mistral-ocr". See Pricing above
        }
    }
]

payload = {
    "model": "google/gemma-3-27b-it",
    "input": input_items,
    "plugins": plugins
}

response = requests.post(url, headers=headers, json=payload)
print(json.dumps(response.json(), indent=2))

```

```typescript TypeScript expandable lines theme={null}
import * as fs from 'fs';

async function encodePDFToBase64(pdfPath: string): Promise<string> {
  const pdfBuffer = await fs.promises.readFile(pdfPath);
  const base64PDF = pdfBuffer.toString('base64');
  return `data:application/pdf;base64,${base64PDF}`;
}

// Read and encode the PDF
const pdfPath = 'path/to/your/document.pdf';
const base64PDF = await encodePDFToBase64(pdfPath);

const response = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'google/gemma-3-27b-it',
    input: [
      {
        role: 'user' as const,
        content: [
          {
            type: 'input_text',
            text: 'What are the main points in this document?',
          },
          {
            type: 'input_file',
            filename: 'document.pdf',
            file_data: base64PDF,
          },
        ],
      },
    ],
    // Optional: Configure PDF processing engine
    // PDF parsing will still work even if the plugin is not explicitly set
    plugins: [
      {
        id: 'file-parser',
        pdf: {
          engine: 'cloudflare-ai', // defaults to "mistral-ocr". See Pricing above
        },
      },
    ],
  }),
});

const data = await response.json();
console.log(data);
```

```go title="Go" lines theme={null}
package main

import (
	"bytes"
	"encoding/base64"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
)

func encodePDFToBase64(pdfPath string) (string, error) {
	pdfBytes, err := os.ReadFile(pdfPath)
	if err != nil {
		return "", err
	}
	return "data:application/pdf;base64," + base64.StdEncoding.EncodeToString(pdfBytes), nil
}

func main() {
	// Read and encode the PDF
	pdfPath := "path/to/your/document.pdf"
	base64PDF, err := encodePDFToBase64(pdfPath)
	if err != nil {
		log.Fatal(err)
	}

	body, _ := json.Marshal(map[string]any{
		"model": "google/gemma-3-27b-it",
		"input": []any{
			map[string]any{
				"role": "user",
				"content": []any{
					map[string]any{
						"type": "input_text",
						"text": "What are the main points in this document?",
					},
					map[string]any{
						"type":      "input_file",
						"filename":  "document.pdf",
						"file_data": base64PDF,
					},
				},
			},
		},
		// Optional: Configure PDF processing engine
		// PDF parsing will still work even if the plugin is not explicitly set
		"plugins": []any{
			map[string]any{
				"id":  "file-parser",
				"pdf": map[string]any{"engine": "cloudflare-ai"}, // defaults to "mistral-ocr". See Pricing above
			},
		},
	})

	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/responses", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	out, _ := io.ReadAll(resp.Body)
	if resp.StatusCode != http.StatusOK {
		log.Fatalf("status %d: %s", resp.StatusCode, out)
	}
	fmt.Println(string(out))
}

```

```text title="Output" theme={null}
{
  id: "gen-1794950500-4coAYmXDmTlTEmntua09",
  object: "response",
  created_at: 1794950500,
  model: "google/gemma-3-27b-it",
  status: "completed",
  completed_at: 1794950505,
  output: [
    {
      id: "msg_tmp_s0jnqtw6k3",
      type: "message",
      role: "assistant",
      status: "completed",
      content: [Array ...],
    }
  ],
  error: null,
  incomplete_details: null,
  access_programs: null,
  tools: [],
  tool_choice: "auto",
  parallel_tool_calls: true,
  max_output_tokens: null,
  temperature: 1,
  top_p: 1,
  presence_penalty: 0,
  frequency_penalty: 0,
  top_logprobs: 0,
  max_tool_calls: null,
  metadata: {},
  background: false,
  previous_response_id: null,
  service_tier: "default",
  truncation: "disabled",
  store: false,
  instructions: null,
  text: {
    format: {
      type: "text",
    },
```

## Skip Parsing Costs

When you send a PDF to the Chat Completions API (`/api/v1/chat/completions`), the response may include file annotations in the assistant's message. These annotations contain structured information about the PDF document that was parsed. By sending these annotations back in subsequent requests, you can avoid re-parsing the same PDF document multiple times, which saves both processing time and costs. The Responses API returns `file_citation` annotations instead, which can't be sent back to skip parsing, so the examples in this section and the annotation schema below use Chat Completions.

Here's how to reuse file annotations:

```python Python expandable lines theme={null}
import requests
import json
import base64
import os
from pathlib import Path

# First, encode and send the PDF
def encode_pdf_to_base64(pdf_path):
    with open(pdf_path, "rb") as pdf_file:
        return base64.b64encode(pdf_file.read()).decode('utf-8')

url = "https://openrouter.ai/api/v1/chat/completions"
headers = {
    "Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
    "Content-Type": "application/json"
}

# Read and encode the PDF
pdf_path = "path/to/your/document.pdf"
base64_pdf = encode_pdf_to_base64(pdf_path)
data_url = f"data:application/pdf;base64,{base64_pdf}"

# Initial request with the PDF
messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "What are the main points in this document?"
            },
            {
                "type": "file",
                "file": {
                    "filename": "document.pdf",
                    "file_data": data_url
                }
            },
        ]
    }
]

payload = {
    "model": "google/gemma-3-27b-it",
    "messages": messages
}

response = requests.post(url, headers=headers, json=payload)
response_data = response.json()
print(json.dumps(response_data, indent=2))

# Store the assistant reply and its file annotations from the response
assistant_message = None
file_annotations = None
if response_data.get("choices") and len(response_data["choices"]) > 0:
    assistant_message = response_data["choices"][0]["message"]
    file_annotations = assistant_message.get("annotations")

# Follow-up request: include the same file plus the annotations from the
# previous assistant message so OpenRouter can skip re-parsing the PDF
if file_annotations:
    follow_up_messages = [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What are the main points in this document?"
                },
                {
                    "type": "file",
                    "file": {
                        "filename": "document.pdf",
                        "file_data": data_url
                    }
                }
            ]
        },
        {
            "role": "assistant",
            "content": assistant_message.get("content") or "",
            "annotations": file_annotations
        },
        {
            "role": "user",
            "content": "Can you elaborate on the second point?"
        }
    ]

    follow_up_payload = {
        "model": "google/gemma-3-27b-it",
        "messages": follow_up_messages
    }

    follow_up_response = requests.post(url, headers=headers, json=follow_up_payload)
    print(json.dumps(follow_up_response.json(), indent=2))
else:
    print("No file annotations returned; nothing to reuse.")

```

```typescript TypeScript expandable lines theme={null}
import fs from 'fs/promises';

async function encodePDFToBase64(pdfPath: string): Promise<string> {
  const pdfBuffer = await fs.readFile(pdfPath);
  const base64PDF = pdfBuffer.toString('base64');
  return `data:application/pdf;base64,${base64PDF}`;
}

// Initial request with the PDF
async function processDocument() {
  // Read and encode the PDF
  const pdfPath = 'path/to/your/document.pdf';
  const base64PDF = await encodePDFToBase64(pdfPath);

  const initialResponse = await fetch(
    'https://openrouter.ai/api/v1/chat/completions',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY_REF}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'google/gemma-3-27b-it',
        messages: [
          {
            role: 'user',
            content: [
              {
                type: 'text',
                text: 'What are the main points in this document?',
              },
              {
                type: 'file',
                file: {
                  filename: 'document.pdf',
                  file_data: base64PDF,
                },
              },
            ],
          },
        ],
      }),
    },
  );

  const initialData = await initialResponse.json();

  // Store the assistant reply and its file annotations from the response
  let assistantMessage = null;
  let fileAnnotations = null;
  if (initialData.choices && initialData.choices.length > 0) {
    assistantMessage = initialData.choices[0].message;
    fileAnnotations = assistantMessage.annotations ?? null;
  }

  // Follow-up request using the annotations (without sending the PDF again)
  if (fileAnnotations) {
    const followUpResponse = await fetch(
      'https://openrouter.ai/api/v1/chat/completions',
      {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${API_KEY_REF}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          model: 'google/gemma-3-27b-it',
          messages: [
            {
              role: 'user',
              content: [
                {
                  type: 'text',
                  text: 'What are the main points in this document?',
                },
                {
                  type: 'file',
                  file: {
                    filename: 'document.pdf',
                    file_data: base64PDF,
                  },
                },
              ],
            },
            {
              role: 'assistant',
              content: assistantMessage.content ?? '',
              annotations: fileAnnotations,
            },
            {
              role: 'user',
              content: 'Can you elaborate on the second point?',
            },
          ],
        }),
      },
    );

    const followUpData = await followUpResponse.json();
    console.log(followUpData);
  }
}

processDocument();
```

```go title="Go" lines theme={null}
package main

import (
	"bytes"
	"encoding/base64"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
)

func post(payload map[string]any) map[string]any {
	body, _ := json.Marshal(payload)
	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/chat/completions", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	out, _ := io.ReadAll(resp.Body)
	if resp.StatusCode != http.StatusOK {
		log.Fatalf("status %d: %s", resp.StatusCode, out)
	}
	var pretty bytes.Buffer
	json.Indent(&pretty, out, "", "  ")
	fmt.Println(pretty.String())

	var data map[string]any
	json.Unmarshal(out, &data)
	return data
}

func main() {
	// First, read and encode the PDF
	pdfBytes, err := os.ReadFile("path/to/your/document.pdf")
	if err != nil {
		log.Fatal(err)
	}
	dataURL := "data:application/pdf;base64," + base64.StdEncoding.EncodeToString(pdfBytes)

	// Initial request with the PDF
	userMessage := map[string]any{
		"role": "user",
		"content": []any{
			map[string]any{"type": "text", "text": "What are the main points in this document?"},
			map[string]any{
				"type": "file",
				"file": map[string]any{"filename": "document.pdf", "file_data": dataURL},
			},
		},
	}

	data := post(map[string]any{
		"model":    "google/gemma-3-27b-it",
		"messages": []any{userMessage},
	})

	// Store the assistant reply and its file annotations from the response
	var content string
	var fileAnnotations []any
	if choices, ok := data["choices"].([]any); ok && len(choices) > 0 {
		msg, _ := choices[0].(map[string]any)["message"].(map[string]any)
		content, _ = msg["content"].(string)
		fileAnnotations, _ = msg["annotations"].([]any)
	}

	// Follow-up request: include the same file plus the annotations from the
	// previous assistant message so OpenRouter can skip re-parsing the PDF
	if len(fileAnnotations) == 0 {
		fmt.Println("No file annotations returned; nothing to reuse.")
		return
	}

	post(map[string]any{
		"model": "google/gemma-3-27b-it",
		"messages": []any{
			userMessage,
			map[string]any{"role": "assistant", "content": content, "annotations": fileAnnotations},
			map[string]any{"role": "user", "content": "Can you elaborate on the second point?"},
		},
	})
}

```

```bash title="cURL" lines theme={null}
#!/bin/bash
# First, encode and send the PDF
PDF_PATH="path/to/your/document.pdf"
WORK_DIR=$(mktemp -d)
trap 'rm -rf "$WORK_DIR"' EXIT

# Keep the encoded PDF in files: a large PDF does not fit in a command-line argument
base64 < "$PDF_PATH" | tr -d '\n' > "$WORK_DIR/pdf.b64"

jq -n --rawfile b64 "$WORK_DIR/pdf.b64" '{
  role: "user",
  content: [
    {type: "text", text: "What are the main points in this document?"},
    {type: "file", file: {filename: "document.pdf", file_data: ("data:application/pdf;base64," + $b64)}}
  ]
}' > "$WORK_DIR/user-msg.json"

# Initial request with the PDF
RESPONSE=$(jq -n --slurpfile msg "$WORK_DIR/user-msg.json" '{model: "google/gemma-3-27b-it", messages: [$msg[0]]}' |
  curl -s https://openrouter.ai/api/v1/chat/completions \
    -H "Authorization: Bearer $OPENROUTER_API_KEY" \
    -H "Content-Type: application/json" \
    -d @-)
echo "$RESPONSE" | jq .

# Store the assistant reply and its file annotations in a file: annotations can
# hold the parsed text of the whole PDF, which is too large for a command-line argument
echo "$RESPONSE" | jq '.choices[0].message // {}' > "$WORK_DIR/assistant-msg.json"
HAS_ANNOTATIONS=$(jq '(.annotations // []) | length > 0' "$WORK_DIR/assistant-msg.json")

# Follow-up request: include the same file plus the annotations from the
# previous assistant message so OpenRouter can skip re-parsing the PDF
if [ "$HAS_ANNOTATIONS" = "true" ]; then
  jq -n --slurpfile msg "$WORK_DIR/user-msg.json" --slurpfile a "$WORK_DIR/assistant-msg.json" '{
    model: "google/gemma-3-27b-it",
    messages: [
      $msg[0],
      {role: "assistant", content: ($a[0].content // ""), annotations: $a[0].annotations},
      {role: "user", content: "Can you elaborate on the second point?"}
    ]
  }' |
    curl -s https://openrouter.ai/api/v1/chat/completions \
      -H "Authorization: Bearer $OPENROUTER_API_KEY" \
      -H "Content-Type: application/json" \
      -d @- | jq .
else
  echo "No file annotations returned; nothing to reuse."
fi

```

```text title="Output" theme={null}
{
  "id": "gen-1794950766-y31tUKFb95aCQUFngXk0",
  "object": "chat.completion",
  "created": 1794950766,
  "model": "google/gemma-3-27b-it",
  "provider": "NextBit",
  "system_fingerprint": "vllm-0.32.0-8349ae92",
  "service_tier": null,
  "choices": [
    {
      "index": 0,
      "logprobs": null,
      "finish_reason": "stop",
      "native_finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "\nOkay, I've analyzed the provided information. It's not a detailed document summary, but here are the main points:\n\n* **It's a sample PDF document.** The document is specifically described as a sample used for OpenRouter documentation.\n* **It's a one-page document.** The description indicates the PDF is only one page long.\n* **It's part of a Python-based OpenRouter sample.** It's located within a directory structure related to Python samples for OpenRouter.\n* **The filename indicates a specific run/version:** The filename (`s_e7f454f8f40bcd83_2701`) suggests it's tied to a particular session or version of sample generation.\n\n**In essence, this is a test or demonstration file meant to accompany code examples for using the OpenRouter API, rather than a document containing substantive information itself.**  Without being able to *see* the contents of the PDF, that's all I can determine.\n",
        "refusal": null,
        "reasoning": null,
        "annotations": [
          {
            "type": "file",
            "file": {
              "hash": "16e2b8f9fda18d247dea9cafc4855187752b813d75e82b360d2c0b9d166cd6f6",
              "name": "/home/ubuntu/.cache/openrouter-docs-samples/python/samples/s_e7f454f8f40bcd83_2701/fixtures/sample.pdf",
              "content": [
                {
                  "type": "text",
                  "text": "<file name=\"/home/ubuntu/.cache/openrouter-docs-samples/python/samples/s_e7f454f8f40bcd83_2701/fixtures/sample.pdf\">"
                },
                {
                  "type": "text",
                  "text": "OpenRouter docs sample fixture: a one-page PDF."
                },
                {
                  "type": "text",
                  "text": "</file>"
                }
              ]
            }
```

> [!NOTE]
>
> When you include the file annotations from a previous response in your subsequent requests, OpenRouter will use this pre-parsed information instead of re-parsing the PDF, which saves processing time and costs. This is especially beneficial for large documents or when using the `mistral-ocr` engine which incurs additional costs.

## File Annotations Schema (Chat Completions)

When OpenRouter parses a PDF sent to Chat Completions, the response includes file annotations in the assistant message. Here is the TypeScript type for the annotation schema:

```typescript lines theme={null}
type FileAnnotation = {
  type: 'file';
  file: {
    hash: string;           // Unique hash identifying the parsed file
    name?: string;          // Original filename (optional)
    content: ContentPart[]; // Parsed content from the file
  };
};

type ContentPart =
  | { type: 'text'; text: string }
  | { type: 'image_url'; image_url: { url: string } };
```

The `content` array contains the parsed content from the PDF, which may include text blocks and images (as base64 data URLs). The `hash` field uniquely identifies the parsed file content and is used to skip re-parsing when you include the annotation in subsequent requests.

## Response Format

### Responses API

The Responses API may include a `file_citation` annotation when the provider cites a parsed file in its output. Parsing a file alone does not guarantee a citation:

```json expandable lines theme={null}
{
  "id": "gen-1234567890",
  "object": "response",
  "created_at": 1234567890,
  "model": "google/gemma-3-27b-it",
  "status": "completed",
  "output": [
    {
      "id": "msg_abc123",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "The document discusses...",
          "annotations": [
            {
              "type": "file_citation",
              "file_id": "abc123...",
              "filename": "document.pdf",
              "index": 0
            }
          ]
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 1000,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 100,
    "output_tokens_details": { "reasoning_tokens": 0 },
    "total_tokens": 1100
  }
}
```

### Chat Completions

Chat Completions returns the parsed file as a reusable `file` annotation on the assistant message (see [Skip Parsing Costs](#skip-parsing-costs)):

```json expandable lines theme={null}
{
  "id": "gen-1234567890",
  "provider": "DeepInfra",
  "model": "google/gemma-3-27b-it",
  "object": "chat.completion",
  "created": 1234567890,
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "The document discusses...",
        "annotations": [
          {
            "type": "file",
            "file": {
              "hash": "abc123...",
              "name": "document.pdf",
              "content": [
                { "type": "text", "text": "Parsed text content..." },
                { "type": "image_url", "image_url": { "url": "data:image/png;base64,..." } }
              ]
            }
          }
        ]
      }
    }
  ],
  "usage": {
    "prompt_tokens": 1000,
    "completion_tokens": 100,
    "total_tokens": 1100
  }
}
```

## Error Responses with Parsed Annotations (Chat Completions)

If OpenRouter successfully parses your PDF but every inference provider then fails to generate a completion, the error response still includes the parsed annotations under `error.metadata.file_annotations`. The shape matches the success-path `FileAnnotation` documented above, so you can hand the same array straight back to OpenRouter on a retry to skip re-parsing.

This applies to the `"mistral-ocr"` and `"cloudflare-ai"` engines, which parse the PDF before sending it to a model. The `"native"` engine doesn't produce annotations because the file is forwarded directly to the model.

```json lines theme={null}
{
  "error": {
    "code": 502,
    "message": "Provider returned an error",
    "metadata": {
      "file_annotations": [
        {
          "type": "file",
          "file": {
            "hash": "abc123...",
            "name": "document.pdf",
            "content": [
              { "type": "text", "text": "Parsed text content..." }
            ]
          }
        }
      ]
    }
  }
}
```

When you read annotations from both the success and error paths, dedupe by `file.hash`. The hash is stable across both shapes for the same parsed file:

```typescript expandable lines theme={null}
// FileAnnotation is the type defined under "File Annotations Schema" above.
function isFileAnnotation(value: unknown): value is FileAnnotation {
  if (typeof value !== 'object' || value === null) return false;
  const candidate = value as { type?: unknown; file?: { hash?: unknown } };
  return (
    candidate.type === 'file' &&
    typeof candidate.file?.hash === 'string'
  );
}

function extractFileAnnotations(response: unknown): FileAnnotation[] {
  if (typeof response !== 'object' || response === null) return [];

  const root = response as {
    choices?: Array<{ message?: { annotations?: unknown[] } }>;
    error?: { metadata?: { file_annotations?: unknown[] } };
  };

  const fromMessage = root.choices?.[0]?.message?.annotations ?? [];
  const fromError = root.error?.metadata?.file_annotations ?? [];

  const seen = new Set<string>();
  const out: FileAnnotation[] = [];
  for (const a of [...fromMessage, ...fromError]) {
    if (isFileAnnotation(a) && !seen.has(a.file.hash)) {
      seen.add(a.file.hash);
      out.push(a);
    }
  }
  return out;
}
```

```python title="Python" lines theme={null}
# FileAnnotation is the shape defined under "File Annotations Schema" above.
def is_file_annotation(value):
    return (
        isinstance(value, dict)
        and value.get("type") == "file"
        and isinstance((value.get("file") or {}).get("hash"), str)
    )


def extract_file_annotations(response):
    if not isinstance(response, dict):
        return []

    choices = response.get("choices") or []
    first = choices[0] if choices and isinstance(choices[0], dict) else {}
    from_message = (first.get("message") or {}).get("annotations") or []
    from_error = ((response.get("error") or {}).get("metadata") or {}).get("file_annotations") or []

    seen = set()
    out = []
    for a in [*from_message, *from_error]:
        if is_file_annotation(a) and a["file"]["hash"] not in seen:
            seen.add(a["file"]["hash"])
            out.append(a)
    return out
```

```go title="Go" lines theme={null}
// Annotations follow the shape defined under "File Annotations Schema" above.
func isFileAnnotation(value any) bool {
	m, ok := value.(map[string]any)
	if !ok || m["type"] != "file" {
		return false
	}
	file, ok := m["file"].(map[string]any)
	if !ok {
		return false
	}
	_, ok = file["hash"].(string)
	return ok
}

func extractFileAnnotations(response any) []map[string]any {
	out := []map[string]any{}
	root, ok := response.(map[string]any)
	if !ok {
		return out
	}

	var fromMessage, fromError []any
	if choices, ok := root["choices"].([]any); ok && len(choices) > 0 {
		if choice, ok := choices[0].(map[string]any); ok {
			if msg, ok := choice["message"].(map[string]any); ok {
				fromMessage, _ = msg["annotations"].([]any)
			}
		}
	}
	if e, ok := root["error"].(map[string]any); ok {
		if md, ok := e["metadata"].(map[string]any); ok {
			fromError, _ = md["file_annotations"].([]any)
		}
	}

	seen := map[string]bool{}
	for _, a := range append(append([]any{}, fromMessage...), fromError...) {
		if !isFileAnnotation(a) {
			continue
		}
		m := a.(map[string]any)
		hash := m["file"].(map[string]any)["hash"].(string)
		if !seen[hash] {
			seen[hash] = true
			out = append(out, m)
		}
	}
	return out
}
```

```bash title="cURL" lines theme={null}
# Collect file annotations from either the success or error shape, deduped by file.hash
extract_file_annotations() {
  jq 'if type != "object" then [] else
      [(.choices[0]?.message?.annotations? // [])[]?, (.error?.metadata?.file_annotations? // [])[]?]
      | map(select(type == "object" and .type == "file" and (.file.hash? | type) == "string"))
      | reduce .[] as $a ([]; if any(.[]; .file.hash == $a.file.hash) then . else . + [$a] end)
    end'
}
```
