How to upload and manage Files via API

It is possible to work with previously uploaded files to perform various operations such as summaries or analysis. To perform these operations, first it is necessary to upload the file using the File API, confirm the success of the operation, and then reference it in the requests to the models that require the file.

Here is a step-by-step guide on how to upload and manage files using the File API.

Step 1: Uploading a File Using the File API

The first step is to upload the file you want to manage. To do this, use the POST /files endpoint of the File API. This endpoint allows you to upload a file and receive a confirmation that the file has been successfully uploaded. The name of the file, which will be used to reference it, can be specified in the fileName parameter or, if not provided, it will be the name of the uploaded file.

Getting your projectId and organizationId

You can get your $PROJECT_ID and $ORGANIZATION_ID using the GET /accessControl/apitoken/validate endpoint of the Organization API. Keep in mind that you can replace $SAIA_ORGANIZATION_APITOKEN with your $SAIA_PROJECT_APITOKEN if needed.

Sample cURL Command

To load a file, use the following sample:

curl -X POST "$BASE_URL/v1/files" \
  -H "Authorization: Bearer $SAIA_PROJECT_APITOKEN" \
  -H "Content-Type: multipart/form-data" \
  -H "fileName: $FILE_NAME" \
  -H "folder: testFolder" \
  -H "organizationId: $ORGANIZATION_ID" \
  -H "projectId: $PROJECT_ID" \
  -F "file=@/path/to/your_file.mp4" 

If you include the fileName parameter, that will be the name you will use to reference the file later.

If you don't include it, you will need to use the original name of the uploaded file. For example, if you upload "file=@/path/to/your_file.mp4", the reference name will be exampleFile (without the extension).

Step 2: Validating the File Upload

Once the file has been successfully uploaded, the response will include information confirming the success of the operation. You don't need to use a dataFileId, but you can check the response to ensure the file was uploaded correctly.

Sample response

{
    "dataFileId": "string",
    "dataFileUrl": "string",
    "success": true
}

Step 3: Create a Chat Assistant (if not created already)

After uploading the file, you need to create a Chat Assistant to process the uploaded content, if you haven't already created one. This is done through the POST /assistant endpoint of the Assistant API.

Sample cURL Command

curl -X POST "$BASE_URL/v1/assistant" \
  -H "Authorization: Bearer $SAIA_PROJECT_APITOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "type": "chat",
      "name": "vertex_ai/gemini-2.0-flash-exp -Test File Upload",
      "prompt": "You are a helpful assistant",
      "llmSettings": {
          "providerName": "vertex_ai",
          "modelName": "gemini-2.0-flash-exp",
          "temperature": 0.10,
          "maxTokens": 8192,
          "uploadFiles": true
      }
  }'

Step 4: Referencing the File

Once the Chat Assistant is set up, you can reference the file in a request to the Assistant for analysis or summary, using the Chat API and specifying the file name in the request body.

Sample cURL Command to Summarize a File:

curl -X POST "$BASE_URL/chat" \
  -H "Authorization: Bearer $SAIA_PROJECT_APITOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "model": "saia:assistant:vertex_ai/gemini-2.0-flash-exp -Test File Upload", /* Using the assistant created in Step 3 named 'vertex_ai/gemini-2.0-flash-exp -Test File Upload' */
       "messages": [
         {
           "role": "user",
           "content": "Provide the content {file:$FILE_NAME}"
         }
       ],
       "stream": false
     }'

Alternative: Inquire About Files - Interact Directly with LLMs

You can also interact with LLMs directly, asking questions about files like images or videos.

curl --location '<BASE_URL>/chat' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <SAIA_PROJECT_APITOKEN>' \
--data '{
    "model": "openai/gpt-4o",
    "max_tokens": 1024,
    "temperature": 0.1,
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": [
                {
                    "text": "Tell me what this is about?",
                    "type": "text"
                },
                {
                    "image_url": {
                        "url": "<IMAGE_FILE_URL>"
                    },
                    "type": "image_url"
                }
            ]
        }
    ]
}'

import requests
import json
import base64

# Define the API endpoint and authentication headers
url = "<BASE_URL>/chat/completions"
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <SAIA_PROJECT_APITOKEN>'
}

# Function to encode a file in Base64 format
def encode_file(file_path):
    """Encodes a file in Base64 format for API submission."""
    with open(file_path, 'rb') as file:
        return base64.b64encode(file.read()).decode('utf-8')

# Replace 'path_to_your_file.mp4' with the actual file path
file_path = "path_to_your_file.mp4"
encoded_file = encode_file(file_path)

# Construct the API request payload
payload = {
    "model": "vertex_ai/gemini-1.5-pro-002",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What's this file about?"
                },
                {
                    "type": "image_url",
                    "image_url": f"data:video/mp4;base64,{encoded_file}"
                }
            ]
        }
    ]
}

# Send the request to the API
response = requests.post(url, headers=headers, json=payload)

# Print response details
print("Status Code:", response.status_code)
print("\nResponse:")
print(json.dumps(response.json(), indent=2))