Skip to main content

​
Attaching Files

Multiple types of files can be attached when calling agents with the Responses API.
  • Images: Via URL (uri) or base64 encoding (bytes)
  • PDFs: Only supported via base64 encoding (bytes) - URI links are not supported for PDFs
  • MIME Types: Required - Must specify correct mimeType (e.g., image/jpeg, application/pdf)
Always verify that your chosen model supports the file types you’re using. Vision models are typically required for image processing and PDF processing

​
Converting Files to Base64

Before attaching PDF files, you need to convert them to base64. Here’s how to do it: 
import base64

def file_to_base64(file_path: str) -> str:
    """Convert a file to base64 string"""
    with open(file_path, "rb") as file:
        return base64.b64encode(file.read()).decode("utf-8")

# Usage
pdf_base64 = file_to_base64("path/to/your/document.pdf")
print(f"Base64 encoded PDF: {pdf_base64}")

​
Examples

​
Attaching an Image

Step 1: Create an Agent 
curl -X POST https://api.orq.ai/v2/agents \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "image-classifier",
  "role": "Image Analyst",
  "description": "Analyzes images and identifies visual content",
  "instructions": "Analyze images and describe what you can see in detail",
  "path": "Default/agents",
  "model": {
    "id": "openai/gpt-4o"
  },
  "settings": {
    "max_iterations": 5,
    "max_execution_time": 600,
    "tools": [
      {
        "type": "current_date"
      }
    ]
  }
}'
Step 2: Call the Agent with an Image 
curl -X POST https://api.orq.ai/v2/agents/image-classifier/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_key": "image-classifier",
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "Look at this map image and tell me what cities, regions, and geographical features you can identify."
      },
      {
        "kind": "file",
        "file": {
          "uri": "https://upload.wikimedia.org/wikipedia/commons/7/73/Herman_Moll_A_New_Map_of_Europe_According_to_the_Newest_Observations_1721.JPG",
          "mimeType": "image/jpeg",
          "name": "europe-map.jpg"
        }
      }
    ]
  }
}'

​
Attaching a PDF

Step 1: Create an Agent 
curl -X POST https://api.orq.ai/v2/agents \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "pdf-analyzer",
  "role": "Document Analyst",
  "description": "Analyzes PDF documents and extracts information",
  "instructions": "Analyze the provided PDF document and answer questions about its content",
  "path": "Default/agents",
  "model": {
    "id": "openai/gpt-4o"
  },
  "settings": {
    "max_iterations": 5,
    "max_execution_time": 600,
    "tools": [
      {
        "type": "current_date"
      }
    ]
  }
}'
Step 2: Call the Agent with a PDF 
curl -X POST https://api.orq.ai/v2/agents/pdf-analyzer/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_key": "pdf-analyzer",
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "Please analyze this PDF document and summarize its key points"
      },
      {
        "kind": "file",
        "file": {
          "bytes": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9MZW5ndGggMTE0L0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nD2OywoCMQxF3/mKu3YRk7ZJk3YpqCOIAzKCH2DSVgp2BtvR/3emDt7lOZyTl0CgVo0KBFhKZRWYClbwBHtwBg7gCM7AX8E3eMGHkMbmdjVdzLfx/XG13Kzn80U8G4+Sny9JyCmJMI25EFFGUs8P/SBJY7+XZElIo36c+72kl6ZJPOglWRgNe8Mw6oZJHqU0HSQvv9vn+wdDDxLsCmVuZHN0cmVhbQplbmRvYmoKMSAwIG9iago8PC9UeXBlL1BhZ2UvTWVkaWFCb3hbMCAwIDYxMiA3OTJdL1Jlc291cmNlczw8L0ZvbnQ8PC9GMSAyIDAgUj4+Pj4vQ29udGVudHMgMyAwIFIvUGFyZW50IDQgMCBSPj4KZW5kb2JqCjIgMCBvYmoKPDwvVHlwZS9Gb250L1N1YnR5cGUvVHlwZTEvQmFzZUZvbnQvSGVsdmV0aWNhPj4KZW5kb2JqCjQgMCBvYmoKPDwvVHlwZS9QYWdlcy9Db3VudCAxL0tpZHNbMSAwIFJdPj4KZW5kb2JqCjUgMCBvYmoKPDwvVHlwZS9DYXRhbG9nL1BhZ2VzIDQgMCBSPj4KZW5kb2JqCjYgMCBvYmoKPDwvUHJvZHVjZXIoU2FtcGxlIFBERikvQ3JlYXRpb25EYXRlKEQ6MjAyNDAxMDEwMDAwMDApPj4KZW5kb2JqCnhyZWYKMCA3CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDE5NyAwMDAwMCBuIAowMDAwMDAwMzA0IDAwMDAwIG4gCjAwMDAwMDAwMTUgMDAwMDAgbiAKMDAwMDAwMDM4NSAwMDAwMCBuIAowMDAwMDAwNDQwIDAwMDAwIG4gCjAwMDAwMDA0ODcgMDAwMDAgbiAKdHJhaWxlcgo8PC9TaXplIDcvUm9vdCA1IDAgUi9JbmZvIDYgMCBSPj4Kc3RhcnR4cmVmCjU3MQolJUVPRko=",
          "mimeType": "application/pdf",
          "name": "sample-document.pdf"
        }
      }
    ]
  }
}'
To learn more about the Create Response API and how to use it, see the API reference.