Process attachments: API

A GenAI task can send the LLM not only documents, but also files attached to the documents.
Supported file types are:
- Plain text files
  Text files are sent to the LLM as is, without any additional encoding.
- Image files: jpeg, png, webp, gif
  Image files are sent to the LLM in base64-encoded strings.
- PDF files
  PDF files are sent to the LLM in base64-encoded strings.
In this article:
- Sending attachments to the LLM

Sending attachments to the LLM

Find a complete example of defining and running a GenAI task that processes attachments in Processing attachments: Studio.

To send documents to the LLM along with their attachments using the API, define and run your GenAI task just as you would without attachments, with the following differences:

When defining the connection string to the LLM, make sure the AI model you're utilizing is capable of processing the files attached to your documents.
E.g., use OpenAI gpt-4.1-mini to process attached image files.
When creating the context object that will be sent to the LLM, include document attachments by specifying them in the context generation script. The LLM will receive and process the attachments along with the main document content.
- Use the with<FileType> method of the ai.genContext object to include document attachments.
- Replace <FileType> with the type of the attachment you want to include:
  withText - for plain text files
  withPng - for PNG image files
  withJpeg - for JPEG image files
  withWebp - for WEBP image files
  withGif - for GIF image files
  withPdf - for PDF files
- Pass with<FileType> the attached file using loadAttachment with the file name as an argument.
  E.g., to include a PNG attachment named electric-circuit.png, use:
```
ai.genContext({ ToyName: this.Name, ToyId: id(this) })
   .withPng(loadAttachment(`electric-circuit.png`));
```
Additional options include:
When defining the task Prompt and JSON schema, make sure to include in the prompt instructions for how the LLM should handle the attachments, and set in the schema fields for any information you expect the LLM to return related to the attachments.
When defining the task Update script, make sure to include logic for how to handle the LLM's responses related to the attachments.

Example

using (var store = new DocumentStore())
{
    // Define the connection string to OpenAI
    var connectionString = new AiConnectionString
    {
        // Connection string name & identifier
        Name = "open-ai-cs",

        // Connection type
        ModelType = AiModelType.Chat,

        // OpenAI connection settings
        OpenAiSettings = new OpenAiSettings(
            apiKey: "your-api-key",
            endpoint: "https://api.openai.com/v1",
            model: "gpt-4.1-mini") // Model capable of handling image processing
    };

    // Deploy the connection string to the server
    var operation = new PutConnectionStringOperation<AiConnectionString>(connectionString);
    var putConnectionStringResult = store.Maintenance.Send(operation);

    // Define the GenAI task configuration
    GenAiConfiguration config = new GenAiConfiguration
    {
        // Task name
        Name = "electric-toy-circuit-description",

        // Unique task identifier
        Identifier = "electric-toy-circuit-description",

        // Connection string to AI model
        ConnectionStringName = "open-ai-cs",

        // Task is enabled
        Disabled = false,

        // Collection associated with the task
        Collection = "ElectricToys",

        // Context generation script - format for objects to be sent to the AI model
        // Include document attachments in the context object using `with<FileType>` methods
        GenAiTransformation = new GenAiTransformation {
            Script = @"
                     ai.genContext({ ToyName: this.Name, ToyId: id(this) })
                    .withPng(loadAttachment(`electric-circuit.png`));"
        },

        // AI model Prompt - the instructions sent to the AI model
        Prompt = "You get documents from an `ElectricToys` document collection. " +  
                 "These are toys for youth that wants to learn simple electronics. " +  
                 "Each document includes a toy's ID and name, and an attached " +  
                 "image with the scheme of a circuit that operates the toy. " +  
                 "Your job is to provide a simple description of up to 20 words " +  
                 "for the circuit, that will be added to the toy's document to " +  
                 "describe how it is operated.",

        // Sample object - a sample response object to format the AI model's replies by
        SampleObject = JsonConvert.SerializeObject( new {
                ToyName = "Toy name as provided by the GenAI task",
                ToyId = "Toy ID as provided by the GenAI task",
                CircuitDescription = "LLM's description of the electric circuit"
                }),

        // Update script - specifies what to do with AI model replies
        UpdateScript = @"    
                       // Embed LLM response in source document  
                       this.CircuitDescription = $output.CircuitDescription;",

        // Max concurrent connections to AI model
        MaxConcurrency = 4
    };

    // Run the task
    var GenAiOperation = new AddGenAiOperation(config);
    var addAiIntegrationTaskResult = store.Maintenance.Send(GenAiOperation);
}

Sending attachments to the LLM​

Example​

Sending attachments to the LLM

Example