跳到主要内容

图片与 PDF

Knox 支持通过 API 发送图片和 PDF 文件。本文将介绍如何使用我们的 API 处理这两种文件类型。

图片和 PDF 文件也可以在聊天中进行交互使用。

图片输入​

对于多模态模型，可以通过 /v1/chat/completions API 实现带有图片的请求，需要在 messages 参数中使用多部分表单格式。image_url 可以是一个 URL 或 base64 编码的图片。请注意，可以通过在 content 数组中添加多个条目来发送多张图片。单次请求可发送的图片数量取决于提供商和模型。由于内容解析方式的差异，我们建议先发送文本提示，再发送图片。如需先发送图片，建议将其放在系统提示中。

使用图片 URL​

以下是通过 URL 发送图片的方式：

import requests
import json

url = "https://api.knox.chat/v1/chat/completions"
headers = {
    "Authorization": f"Bearer {API_KEY_REF}",
    "Content-Type": "application/json"
}

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "What's in this image?"
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
                }
            }
        ]
    }
]

payload = {
    "model": "google/gemini-2.5-flash",
    "messages": messages
}

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

使用 Base64 编码图片​

对于本地存储的图片，可以使用 Base64 编码进行传输。具体步骤如下：

import requests
import json
import base64
from pathlib import Path

def encode_image_to_base64(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode('utf-8')

url = "https://api.knox.chat/v1/chat/completions"
headers = {
    "Authorization": f"Bearer {API_KEY_REF}",
    "Content-Type": "application/json"
}

# Read and encode the image
image_path = "path/to/your/image.jpg"
base64_image = encode_image_to_base64(image_path)
data_url = f"data:image/jpeg;base64,{base64_image}"

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "What's in this image?"
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": data_url
                }
            }
        ]
    }
]

payload = {
    "model": "google/gemini-2.5-flash",
    "messages": messages
}

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

支持的图片内容类型包括：

  • image/png
  • image/jpeg
  • image/webp

PDF 支持​

Knox 通过 /v1/chat/completions API 提供 PDF 处理功能。PDF 文件可以通过 file 内容类型，以 base64 编码的数据 URL 形式在消息数组中发送。此功能适用于 Knox 上的任何模型。

信息

如果模型原生支持文件输入，PDF 将直接传递给模型。如果模型不原生支持文件输入，Knox 会解析文件并将解析结果传递给请求的模型。

请注意，可以将多个 PDF 作为独立的 content 数组条目发送。单次请求可发送的 PDF 数量取决于服务提供商和模型。由于内容解析方式的差异，我们建议先发送文本提示，再发送 PDF。如需先发送 PDF，建议将其放在系统提示中。

插件配置​

要配置 PDF 处理功能，请在请求中使用 plugins 参数。Knox 提供多种 PDF 处理引擎，具有不同的功能和定价：

{
  plugins: [
    {
      id: 'file-parser',
      pdf: {
        engine: 'pdf-text', // or 'mistral-ocr' or 'native'
      },
    },
  ],
}

定价​

Knox 提供多种 PDF 处理引擎：

  1. "mistral-ocr"：适用于扫描文档或包含图片的 PDF（每 1000 页 $2）。
  2. "pdf-text"：适用于结构良好、文本清晰的 PDF（免费）。
  3. "native"：仅适用于原生支持文件输入的模型（按输入 Token 计费）。

如果未明确指定引擎，Knox 将优先使用模型的原生文件处理能力。如不可用，则默认使用 "mistral-ocr" 引擎。

处理 PDF​

以下是发送和处理 PDF 的方式：

import requests
import json
import base64
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://api.knox.chat/v1/chat/completions"
headers = {
    "Authorization": f"Bearer {API_KEY_REF}",
    "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}"

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
                }
            },
        ]
    }
]

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

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

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

跳过解析费用​

当你向 API 发送 PDF 文件时，响应中可能会在助手消息中包含文件注解（annotations）。这些注解记录了已解析 PDF 文档的结构化信息。如果在后续请求中重新发送这些注解，可以避免重复解析同一 PDF 文档，从而节省处理时间和成本。

以下是重用文件注解的方式：

import requests
import json
import base64
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://api.knox.chat/v1/chat/completions"
headers = {
    "Authorization": f"Bearer {API_KEY_REF}",
    "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()

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

# Follow-up request using the annotations (without sending the PDF again)
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": "The document contains information about...",
            "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(follow_up_response.json())
信息

当你在后续请求中包含来自先前响应的文件注解时，Knox 将直接使用这些预解析的信息， 而不会重新解析 PDF 文件，从而节省处理时间和成本。此机制对于大型文档或使用会产生额外费用的 mistral-ocr 引擎时尤为有益。