​
Overview

Attachments allow you to include files, images, documents, and other media in your requests to enhance AI workflows with multimodal capabilities. The Itzam SDK supports sending attachments in two formats: base64-encoded data or remote URLs.

​
Supported Formats

Attachments can be sent in the following ways:

  • Base64 encoded data: For files you have locally or want to upload directly
  • Remote URLs: For files hosted on the web that the AI can access

​
Using URLs

const response = await itzam.generateText({
  input: "What do you see in this image?",
  workflowSlug: "vision-workflow",
  attachments: [
    {
      file: "https://example.com/document.pdf",
    },
  ],
});

​
Using Base64

const response = await itzam.generateText({
  input: "Analyze this document",
  workflowSlug: "document-analysis",
  attachments: [
    {
      file: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==",
    },
  ],
});

​
Usage with Generate Object

import Itzam from "itzam";
import { z } from "zod";

const itzam = new Itzam("YOUR_API_KEY");

const analysisSchema = z.object({
  objects: z.array(z.string()),
  colors: z.array(z.string()),
  description: z.string(),
  confidence: z.number().min(0).max(1),
});

const response = await itzam.generateObject({
  input: "Analyze this image and extract key information",
  workflowSlug: "image-analysis",
  schema: analysisSchema,
  attachments: [
    {
      file: "https://example.com/image.jpg",
    },
  ],
});

​
Multiple Attachments

You can send multiple attachments in a single request:

const response = await itzam.generateText({
  input: "Compare these documents and images",
  workflowSlug: "multi-modal-analysis",
  attachments: [
    {
      file: "https://example.com/document1.pdf",
      mimeType: "application/pdf",
    },
    {
      file: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
      mimeType: "image/jpeg",
    },
  ],
});

​
Attachment Object Structure

PropertyTypeRequiredDescription
filestringYesThe file data as base64 string or URL
mimeTypestringNoThe MIME type of the file (e.g., “image/png”, “application/pdf”). Auto-detected

​
Supported MIME Types

Common MIME types that work well with AI models:

​
Images

  • image/jpeg - JPEG images
  • image/png - PNG images
  • image/gif - GIF images
  • image/webp - WebP images
  • image/svg+xml - SVG images

​
Documents

  • application/pdf - PDF documents
  • text/plain - Plain text files
  • text/markdown - Markdown files
  • application/msword - Word documents
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document - Word documents (.docx)

​
Data

  • application/json - JSON files
  • text/csv - CSV files
  • application/xml - XML files

​
Best Practices

​
File Size

  • Keep file sizes reasonable for better performance
  • Large files may increase processing time and costs
  • Consider compressing images when possible

​
MIME Type Specification

// Always try to specify MIME type for better processing
{
  file: base64Data,
  mimeType: "image/jpeg" // Helps the AI understand the file type
}

​
URLs

// URLs must be publicly accessible
{
  file: "https://example.com/public-image.jpg", // ✅ Good
  mimeType: "image/jpeg"
}

// Private URLs requiring authentication won't work
{
  file: "https://private-bucket.s3.amazonaws.com/private-file.pdf", // ❌ Won't work
  mimeType: "application/pdf"
}

​
Error Handling

Attachment-related errors will be thrown as ItzamError instances:

try {
  const response = await itzam.generateText({
    input: "Analyze this",
    workflowSlug: "analysis",
    attachments: [
      {
        file: "invalid-url",
        mimeType: "image/jpeg",
      },
    ],
  });
} catch (error) {
  if (error instanceof ItzamError) {
    console.error("Attachment error:", error.message);
  }
}