Ask AI

Files API Reference

The Files API allows you to upload, list, retrieve, and delete files that can be used across various AvalAI endpoints. This is AvalAI's first native service layer, providing an OpenAI-compatible file management system that works seamlessly with all 26+ providers and 410+ models.

Files API status: v1/files is available for upload, listing, retrieval, deletion, and file reuse across supported AvalAI routes. Pricing, storage quotas, and model compatibility can vary by account tier and endpoint; check the limits below and contact t.me/AvalAISupport for account-specific needs.

Why Use the Files API?

Using the Files API instead of inline base64 or URL file inputs offers several advantages:

Avoid Repeated Large File Transfers - Upload once, reference by file_id in subsequent requests
Improved Performance - Files are stored server-side and retrieved internally, reducing latency
Reduced Network Overhead - Base64 encoding increases file size by ~33%; using file_id is just a short string
Reusable Across Endpoints - Works with v1/chat/completions, v1/responses, v1/messages, v1/ocr, and v1/images/edits

Base URL

https://api.avalai.ir/v1

Authentication

All Files API requests require authentication via Bearer token:

http

Authorization: Bearer YOUR_AVALAI_API_KEY

Supported Endpoints

Files uploaded through the Files API can be used with the following endpoints:

Endpoint	Description
`v1/chat/completions`	OpenAI-compatible chat completions
`v1/responses`	OpenAI Responses API
`v1/messages`	Anthropic Messages API
`v1/ocr`	OCR processing endpoint
`v1/images/edits`	Image editing endpoints

Upload File

Upload a file that can be used across various endpoints.

POST https://api.avalai.ir/v1/files

Request Body (Multipart Form)

Parameter	Type	Required	Description
`file`	file	Yes	The file object to be uploaded. Maximum size: 128MB per upload.
`purpose`	string	Yes	The intended purpose of the uploaded file. See Supported Purposes.
`expires_after`	object	No	Optional expiration policy for the file.

Supported Purposes

Purpose	Description
`assistants`	Used in the Assistants API
`batch`	Used in the Batch API
`fine-tune`	Used for fine-tuning models
`vision`	Images used for vision fine-tuning
`user_data`	Flexible file type for any purpose
`evals`	Used for evaluation datasets
`others`	AvalAI-specific: General purpose for any other use case

Purpose Selection

Use user_data for files you plan to pass as input_file model inputs in /v1/responses or other supported routes.
Use batch only for JSONL files that will become Batch API input files; batch files follow the provider's expiration policy and OpenAI's reference default is 30 days.
Use assistants only for hosted File Search or Assistants-style vector-store workflows when those surfaces are enabled.
Use fine-tune only for JSONL training or validation datasets that match the selected fine-tuning route's required schema.
Use vision only for image workflows that require File API image storage; supported image types in OpenAI-style vision flows are typically png, jpg, gif, and webp, and only vision-capable models can consume them.
Delete files you no longer need. Non-batch files may persist until manual deletion unless you set expires_after. See Data Controls for retention planning.

OpenAI-Compatible File Rules

OpenAI's reference Files API supports multiple downstream surfaces, but each surface has its own file constraints. Adapt upstream examples to AvalAI's current route limits before shipping:

Surface	Practical rule
`/v1/responses` direct file input	Use `purpose="user_data"` and reference the file as an `input_file` with `file_id`; `file_url` and base64 `file_data` are alternatives when you do not need reuse.
Batch API	Use JSONL request files only; OpenAI's reference Batch API limit is 200MB per input file, while AvalAI account/upload limits may be lower.
Fine-tuning	Use JSONL datasets and validate the exact chat/completions schema required by the target fine-tuning endpoint.
Hosted File Search / Assistants-style tools	Use `purpose="assistants"` only when the hosted retrieval/vector-store surface is enabled for your account.
Image and vision flows	Use image-capable models and supported image MIME types; tools cannot automatically read image content unless the route explicitly attaches the file to that tool.

Expiration Policy Object

Parameter	Type	Required	Description
`anchor`	string	Yes	The anchor point for expiration. Currently only `"created_at"` is supported.
`seconds`	integer	Yes	Number of seconds after the anchor time when the file will expire.

Examples

bash

curl https://api.avalai.ir/v1/files \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -F purpose="user_data" \
  -F file="@document.pdf"

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

# Upload a file
file = client.files.create(file=open("document.pdf", "rb"), purpose="user_data")

print(f"File uploaded: {file.id}")

# Upload with expiration (30 days)
file_with_expiry = client.files.create(
    file=open("temp_data.jsonl", "rb"),
    purpose="batch",
    expires_after={"anchor": "created_at", "seconds": 2592000},  # 30 days
)

javascript

import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.AVALAI_API_KEY,
    baseURL: "https://api.avalai.ir/v1",
});

// Upload a file
const file = await client.files.create({
    file: fs.createReadStream("document.pdf"),
    purpose: "user_data",
});

console.log(`File uploaded: ${file.id}`);

// Upload with expiration (30 days)
const fileWithExpiry = await client.files.create({
    file: fs.createReadStream("temp_data.jsonl"),
    purpose: "batch",
    expires_after: {
        anchor: "created_at",
        seconds: 2592000,
    },
});

go

package main

import (
	"context"
	"fmt"
	"io"
	"os"

	"github.com/openai/openai-go"
	"github.com/openai/openai-go/option"
)

func main() {
	client := openai.NewClient(
		option.WithAPIKey(os.Getenv("AVALAI_API_KEY")),
		option.WithBaseURL("https://api.avalai.ir/v1"),
	)

	file, err := os.Open("document.pdf")
	if err != nil {
		panic(err)
	}
	defer file.Close()

	uploaded, err := client.Files.New(context.Background(), openai.FileNewParams{
		File:    openai.F[io.Reader](file),
		Purpose: openai.F(openai.FilePurposeUserData),
	})
	if err != nil {
		panic(err)
	}

	fmt.Printf("File uploaded: %s\n", uploaded.ID)
}

php

<?php

$apiKey = getenv('AVALAI_API_KEY');
$apiUrl = 'https://api.avalai.ir/v1/files';

$file = new CURLFile('document.pdf', 'application/pdf', 'document.pdf');

$data = [
    'file' => $file,
    'purpose' => 'user_data'
];

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
]);

$response = curl_exec($ch);
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpcode >= 400) {
    echo "Error: " . $httpcode . "\n";
    echo $response;
} else {
    $fileData = json_decode($response, true);
    echo "File uploaded: " . $fileData['id'] . "\n";
}
?>

Response

json

{
  "id": "file-EyVi0MrxuKTgBrvkVas5ZTGz",
  "object": "file",
  "bytes": 13264,
  "created_at": 1767210968,
  "expires_at": null,
  "filename": "document.pdf",
  "purpose": "user_data",
  "status": null,
  "status_details": null
}

List Files

Returns a list of files that belong to your organization.

GET https://api.avalai.ir/v1/files

Query Parameters

Parameter	Type	Required	Description
`purpose`	string	No	Filter by purpose (e.g., `user_data`, `fine-tune`).
`limit`	integer	No	Number of files to retrieve (1-10000). Default: 10000.
`order`	string	No	Sort order by `created_at`. Either `asc` or `desc`. Default: `desc`.
`after`	string	No	A cursor for pagination. Get files after this file ID.

Examples

bash

# List all files
curl https://api.avalai.ir/v1/files \
  -H "Authorization: Bearer $AVALAI_API_KEY"

# List files with specific purpose
curl "https://api.avalai.ir/v1/files?purpose=user_data&limit=10" \
  -H "Authorization: Bearer $AVALAI_API_KEY"

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

# List all files
files = client.files.list()
for file in files.data:
    print(f"{file.id}: {file.filename} ({file.bytes} bytes)")

# List files with specific purpose
user_files = client.files.list(purpose="user_data")

javascript

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.AVALAI_API_KEY,
    baseURL: "https://api.avalai.ir/v1",
});

// List all files
const files = await client.files.list();
for (const file of files.data) {
    console.log(`${file.id}: ${file.filename} (${file.bytes} bytes)`);
}

// List files with specific purpose
const userFiles = await client.files.list({ purpose: "user_data" });

go

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go"
	"github.com/openai/openai-go/option"
)

func main() {
	client := openai.NewClient(
		option.WithAPIKey(os.Getenv("AVALAI_API_KEY")),
		option.WithBaseURL("https://api.avalai.ir/v1"),
	)

	files, err := client.Files.List(context.Background(), openai.FileListParams{})
	if err != nil {
		panic(err)
	}

	for _, file := range files.Data {
		fmt.Printf("%s: %s (%d bytes)\n", file.ID, file.Filename, file.Bytes)
	}
}

php

<?php

$apiKey = getenv('AVALAI_API_KEY');
$apiUrl = 'https://api.avalai.ir/v1/files';

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
foreach ($data['data'] as $file) {
    echo $file['id'] . ": " . $file['filename'] . " (" . $file['bytes'] . " bytes)\n";
}
?>

Response

json

{
  "object": "list",
  "data": [
    {
      "id": "file-EyVi0MrxuKTgBrvkVas5ZTGz",
      "object": "file",
      "bytes": 13264,
      "created_at": 1767210968,
      "expires_at": null,
      "filename": "document.pdf",
      "purpose": "user_data",
      "status": null,
      "status_details": null
    },
    {
      "id": "file-NWU5LYel4DIxFCITnrVRLLcA",
      "object": "file",
      "bytes": 53,
      "created_at": 1766585221,
      "expires_at": null,
      "filename": "mydata.jsonl",
      "purpose": "fine-tune",
      "status": null,
      "status_details": null
    }
  ],
  "first_id": "file-EyVi0MrxuKTgBrvkVas5ZTGz",
  "last_id": "file-NWU5LYel4DIxFCITnrVRLLcA",
  "has_more": false
}

Retrieve File

Returns information about a specific file.

GET https://api.avalai.ir/v1/files/{file_id}

Path Parameters

Parameter	Type	Required	Description
`file_id`	string	Yes	The ID of the file to retrieve.

Examples

bash

curl https://api.avalai.ir/v1/files/file-abc123 \
  -H "Authorization: Bearer $AVALAI_API_KEY"

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

file = client.files.retrieve("file-abc123")
print(f"Filename: {file.filename}")
print(f"Size: {file.bytes} bytes")
print(f"Purpose: {file.purpose}")

javascript

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.AVALAI_API_KEY,
    baseURL: "https://api.avalai.ir/v1",
});

const file = await client.files.retrieve("file-abc123");
console.log(`Filename: ${file.filename}`);
console.log(`Size: ${file.bytes} bytes`);
console.log(`Purpose: ${file.purpose}`);

go

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go"
	"github.com/openai/openai-go/option"
)

func main() {
	client := openai.NewClient(
		option.WithAPIKey(os.Getenv("AVALAI_API_KEY")),
		option.WithBaseURL("https://api.avalai.ir/v1"),
	)

	file, err := client.Files.Get(context.Background(), "file-abc123")
	if err != nil {
		panic(err)
	}

	fmt.Printf("Filename: %s\n", file.Filename)
	fmt.Printf("Size: %d bytes\n", file.Bytes)
	fmt.Printf("Purpose: %s\n", file.Purpose)
}

php

<?php

$apiKey = getenv('AVALAI_API_KEY');
$fileId = 'file-abc123';
$apiUrl = "https://api.avalai.ir/v1/files/{$fileId}";

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
]);

$response = curl_exec($ch);
curl_close($ch);

$file = json_decode($response, true);
echo "Filename: " . $file['filename'] . "\n";
echo "Size: " . $file['bytes'] . " bytes\n";
echo "Purpose: " . $file['purpose'] . "\n";
?>

Response

json

{
  "id": "file-EyVi0MrxuKTgBrvkVas5ZTGz",
  "object": "file",
  "bytes": 13264,
  "created_at": 1767210968,
  "expires_at": null,
  "filename": "document.pdf",
  "purpose": "user_data",
  "status": null,
  "status_details": null
}

Delete File

Delete a file from your organization's storage.

DELETE https://api.avalai.ir/v1/files/{file_id}

Path Parameters

Parameter	Type	Required	Description
`file_id`	string	Yes	The ID of the file to delete.

Examples

bash

curl -X DELETE https://api.avalai.ir/v1/files/file-abc123 \
  -H "Authorization: Bearer $AVALAI_API_KEY"

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

deleted = client.files.delete("file-abc123")
print(f"Deleted: {deleted.deleted}")

javascript

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.AVALAI_API_KEY,
    baseURL: "https://api.avalai.ir/v1",
});

const deleted = await client.files.del("file-abc123");
console.log(`Deleted: ${deleted.deleted}`);

go

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go"
	"github.com/openai/openai-go/option"
)

func main() {
	client := openai.NewClient(
		option.WithAPIKey(os.Getenv("AVALAI_API_KEY")),
		option.WithBaseURL("https://api.avalai.ir/v1"),
	)

	deleted, err := client.Files.Delete(context.Background(), "file-abc123")
	if err != nil {
		panic(err)
	}

	fmt.Printf("Deleted: %v\n", deleted.Deleted)
}

php

<?php

$apiKey = getenv('AVALAI_API_KEY');
$fileId = 'file-abc123';
$apiUrl = "https://api.avalai.ir/v1/files/{$fileId}";

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
echo "Deleted: " . ($result['deleted'] ? 'true' : 'false') . "\n";
?>

Response

json

{
  "id": "file-abc123",
  "object": "file",
  "deleted": true
}

Retrieve File Content

Download the content of a file.

GET https://api.avalai.ir/v1/files/{file_id}/content

Path Parameters

Parameter	Type	Required	Description
`file_id`	string	Yes	The ID of the file to download.

Examples

bash

# Download file content
curl https://api.avalai.ir/v1/files/file-abc123/content \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  --output downloaded_file.pdf

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

# Download file content
content = client.files.content("file-abc123")

# Save to file
with open("downloaded_file.pdf", "wb") as f:
    f.write(content.read())

javascript

import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.AVALAI_API_KEY,
    baseURL: "https://api.avalai.ir/v1",
});

// Download file content
const content = await client.files.content("file-abc123");
const buffer = Buffer.from(await content.arrayBuffer());
fs.writeFileSync("downloaded_file.pdf", buffer);

go

package main

import (
	"context"
	"io"
	"os"

	"github.com/openai/openai-go"
	"github.com/openai/openai-go/option"
)

func main() {
	client := openai.NewClient(
		option.WithAPIKey(os.Getenv("AVALAI_API_KEY")),
		option.WithBaseURL("https://api.avalai.ir/v1"),
	)

	content, err := client.Files.Content(context.Background(), "file-abc123")
	if err != nil {
		panic(err)
	}

	file, err := os.Create("downloaded_file.pdf")
	if err != nil {
		panic(err)
	}
	defer file.Close()

	io.Copy(file, content.Body)
}

php

<?php

$apiKey = getenv('AVALAI_API_KEY');
$fileId = 'file-abc123';
$apiUrl = "https://api.avalai.ir/v1/files/{$fileId}/content";

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
]);

$content = curl_exec($ch);
curl_close($ch);

file_put_contents('downloaded_file.pdf', $content);
echo "File downloaded successfully\n";
?>

File Object

The file object represents a document that has been uploaded to AvalAI.

Field	Type	Description
`id`	string	Unique identifier for the file (e.g., `file-EyVi0MrxuKTgBrvkVas5ZTGz`).
`object`	string	Object type, always `"file"`.
`bytes`	integer	Size of the file in bytes.
`created_at`	integer	Unix timestamp when the file was created.
`expires_at`	integer or null	Unix timestamp when the file will expire, or null if it doesn't expire.
`filename`	string	Name of the file.
`purpose`	string	The intended purpose of the file.
`status`	string or null	The status of the file (used for async operations).
`status_details`	string or null	Additional details about the status.

Rate Limits

File operations are rate-limited based on your account tier:

Operations Rate Limits (per minute)

Tier	Uploads	Downloads	Deletes
0 (Free)	3	5	10
1	10	100	100
2	50	250	250
3	250	500	500
4	500	1,000	1,000
5	1,500	2,000	5,000

Storage Limits by Tier

Each account tier has a maximum total storage limit. Once exhausted, uploads are blocked until you:

Free up storage by deleting files, OR
Upgrade to a higher tier

Tier	Max Storage
0 (Free)	250 MB
1	2 GB
2	5 GB
3	15 GB
4	50 GB
5	200 GB

For more information about tiers, see Rate Limits.

Using Files in API Calls

Once you've uploaded a file, you can reference it by file_id in supported endpoints.

⚠️ Model Compatibility Note: File support is endpoint- and model-dependent. In /v1/responses, use input_file.file_id for files uploaded with purpose="user_data", input_file.file_url for public documents, or input_file.filename plus input_file.file_data for inline Base64 documents. Vision-capable OpenAI models can use PDF input_file items that combine extracted text with page images; non-PDF documents are generally text-extracted, and spreadsheets should be treated as summarized/augmented context rather than exact full-cell data. In /v1/chat/completions, Gemini and other document-capable models may still be the better choice for PDF-style file parts. Check model documentation and use retrieval for large document sets.

Example: Chat Completions with File

bash

curl https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Summarize this document"
          },
          {
            "type": "file",
            "file": {
              "file_id": "file-EyVi0MrxuKTgBrvkVas5ZTGz"
            }
          }
        ]
      }
    ]
  }'

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

# Use uploaded file in chat completion
# Note: File support depends on the selected model and endpoint.
# Gemini remains a good Chat Completions choice for PDF-style file parts.
response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Summarize this document"},
                {"type": "file", "file": {"file_id": "file-EyVi0MrxuKTgBrvkVas5ZTGz"}},
            ],
        }
    ],
)

print(response.choices[0].message.content)

javascript

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.AVALAI_API_KEY,
    baseURL: "https://api.avalai.ir/v1",
});

// Use uploaded file in chat completion
// Note: File support depends on the selected model and endpoint.
// Gemini remains a good Chat Completions choice for PDF-style file parts.
const response = await client.chat.completions.create({
    model: "gemini-2.5-flash",
    messages: [
        {
            role: "user",
            content: [
                { type: "text", text: "Summarize this document" },
                { type: "file", file: { file_id: "file-EyVi0MrxuKTgBrvkVas5ZTGz" } },
            ],
        },
    ],
});

console.log(response.choices[0].message.content);

go

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go"
	"github.com/openai/openai-go/option"
)

func main() {
	client := openai.NewClient(
		option.WithAPIKey(os.Getenv("AVALAI_API_KEY")),
		option.WithBaseURL("https://api.avalai.ir/v1"),
	)

	// Use uploaded file in chat completion
	response, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
		Model: openai.F("gemini-2.5-flash"),
		Messages: openai.F([]openai.ChatCompletionMessageParamUnion{
			openai.UserMessageParts(
				openai.TextPart("Summarize this document"),
				openai.FilePart("file-abc123"),
			),
		}),
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(response.Choices[0].Message.Content)
}

php

<?php

$apiKey = getenv('AVALAI_API_KEY');
$apiUrl = 'https://api.avalai.ir/v1/chat/completions';

$data = [
    'model' => 'gemini-2.5-flash',
    'messages' => [
        [
            'role' => 'user',
            'content' => [
                ['type' => 'text', 'text' => 'Summarize this document'],
                ['type' => 'file', 'file' => ['file_id' => 'file-abc123']],
            ],
        ],
    ],
];

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey,
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
echo $result['choices'][0]['message']['content'] . "\n";
?>

Responses API version This version uses `gpt-5.5` because `gemini-2.5-flash` may not be enabled for `/v1/responses` in the current AvalAI model data.

Use this version when the selected model supports /v1/responses. messages moves to input, and the final text is read from response.output_text.

PythonJavaScriptBash

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model="gpt-5.5",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Summarize the uploaded file."},
                {"type": "input_file", "file_id": "file_abc123"},
            ],
        }
    ],
)

print(response.output_text)

javascript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const response = await client.responses.create({
  model: "gpt-5.5",
  input: [
    {
      role: "user",
      content: [
        { type: "input_text", text: "Summarize the uploaded file." },
        { type: "input_file", file_id: "file_abc123" },
      ],
    },
  ],
});

console.log(response.output_text);

bash

curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '
  {
    "model": "gpt-5.5",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Summarize the uploaded file."
          },
          {
            "type": "input_file",
            "file_id": "file_abc123"
          }
        ]
      }
    ]
  }'

messages → input
system message → instructions or a developer item
choices[0].message.content → response.output_text
for tools and multimodal output, inspect response.output by item type.

Limitations

Current Limitations

Maximum file size: 128MB per upload
Storage limits: Based on tier (250MB to 200GB)
Upstream examples may be larger: OpenAI reference examples mention higher per-file and project-level limits for some products; this page documents AvalAI's public file-upload and tier limits.

Supported Endpoints

File IDs can currently be used with:

v1/chat/completions
v1/responses
v1/messages
v1/ocr
v1/images/edits

Storage & Security

Storage Infrastructure

Files are stored across enterprise-grade cloud providers:

AWS S3
Google Cloud Platform (GCP)
Cloudflare

Security

Treat uploaded files as customer data: avoid secrets unless they are required for the task, use short expires_after windows for temporary processing, and delete files when workflows finish.
Do not assume every downstream provider or tool has the same retention behavior. Check the selected route, model, and account controls before sending regulated or highly sensitive files.
For sensitive workloads, prefer file IDs over inline base64 in logs and prompts, and redact filenames or metadata that may contain personal data.

Security Reporting

If you discover a security vulnerability, please report it to:

Email: security@avalai.ir
Bug bounties are available for critical security issues that could put user data at risk

Error Handling

Status Code	Description
400	Bad Request - Invalid file or missing parameters
401	Unauthorized - Invalid API key
403	Forbidden - You don't have permission to access this file
404	Not Found - File not found
413	Payload Too Large - File exceeds 128MB limit
429	Too Many Requests - Rate limit exceeded
507	Insufficient Storage - Storage limit exceeded for your tier

File Inputs Guide - Learn about different methods to provide file inputs
Rate Limits - Understand rate limits and tiers
Chat Completions - Use files in chat completions
Authentication - Learn about authentication methods

Support

Bug Reports: t.me/AvalAISupport
Security Issues: security@avalai.ir

Files API Reference ​

Why Use the Files API? ​

Base URL ​

Authentication ​

Supported Endpoints ​

Upload File ​

Request Body (Multipart Form) ​

Supported Purposes ​

Purpose Selection ​

OpenAI-Compatible File Rules ​

Expiration Policy Object ​

Examples ​

Response ​

List Files ​

Query Parameters ​

Examples ​

Response ​

Retrieve File ​

Path Parameters ​

Examples ​

Response ​

Delete File ​

Path Parameters ​

Examples ​

Response ​

Retrieve File Content ​

Path Parameters ​

Examples ​

File Object ​

Rate Limits ​

Operations Rate Limits (per minute) ​

Storage Limits by Tier ​

Using Files in API Calls ​

Example: Chat Completions with File ​

Limitations ​

Current Limitations ​

Supported Endpoints ​

Storage & Security ​

Storage Infrastructure ​

Security ​

Security Reporting ​

Error Handling ​

Related Resources ​

Support ​

Files API Reference

Why Use the Files API?

Base URL

Authentication

Supported Endpoints

Upload File

Request Body (Multipart Form)

Supported Purposes

Purpose Selection

OpenAI-Compatible File Rules

Expiration Policy Object

Examples

Response

List Files

Query Parameters

Examples

Response

Retrieve File

Path Parameters

Examples

Response

Delete File

Path Parameters

Examples

Response

Retrieve File Content

Path Parameters

Examples

File Object

Rate Limits

Operations Rate Limits (per minute)

Storage Limits by Tier

Using Files in API Calls

Example: Chat Completions with File

Limitations

Current Limitations

Supported Endpoints

Storage & Security

Storage Infrastructure

Security

Security Reporting

Error Handling

Related Resources

Support