---
title: "Files API в AI Gateway"
---

# Files API в AI Gateway

> Полный индекс документации для ИИ-агентов: [llms.txt](https://timeweb.cloud/llms.txt).

Files API позволяет загружать файлы в AI Gateway и передавать их моделям в запросах. Это удобно, когда модели нужно обработать документ, таблицу, текстовый файл или другой материал, который не требуется каждый раз вставлять в тело запроса.

Файл загружается один раз, после чего AI Gateway возвращает его идентификатор. Этот идентификатор можно использовать в последующих запросах к модели.

## Подготовка токена

Для работы с Files API нужен [API-ключ AI Gateway](https://timeweb.cloud/docs/ai-agents/api-usage/ai-gateway#sozdanie-api-klucha). Создать ключ можно в разделе «ИИ-сервисы» во вкладке «AI Gateway» → «API-ключи».

В примерах используется переменная окружения `TIMEWEB_AI_TOKEN`, чтобы не указывать ключ напрямую в каждом запросе. На Linux и macOS переменную можно задать командой:

```bash
export TIMEWEB_AI_TOKEN="ваш_API-ключ"
```

После этого значение переменной будет доступно в текущей сессии терминала. Чтобы переменная сохранялась после перезапуска терминала, добавьте эту же строку в файл конфигурации вашей оболочки, например `~/.zshrc` для zsh или `~/.bashrc` для bash.

## Методы API

Ниже приведены методы для работы с файлами через API. Для запросов к уже загруженному файлу используется идентификатор `file_id`, который возвращается при загрузке.

### Загрузка файла

Чтобы загрузить файл, отправьте POST-запрос на эндпоинт `/v1/files`:

```bash
curl --request POST \
 --url https://api.timeweb.ai/v1/files \
 --header "authorization: Bearer $TIMEWEB_AI_TOKEN" \
 --header "content-type: multipart/form-data" \
 --form purpose=user_data \
 --form "file=@<file_path>" \
 --form "target_model_names=openai/gpt-4.1"
```

Параметры:

-   `purpose` — назначение файла. В AI Gateway поддерживаются только значения `user_data` и messages. Значение `user_data` используется для работы с файлами в запросах к моделям, `messages` доступно при работе с моделями Claude. Другие значения `purpose` не поддерживаются.
    
-   `file` — путь к локальному файлу. Перед путем указывается символ `@`, например `file=@/Users/timeweb_cloud/test.txt`.
    
-   `target_model_names` — имена моделей, для которых загружается файл. Если файл должен быть доступен нескольким моделям, перечислите их через запятую, например `target_model_names=openai/gpt-4.1,openai/gpt-5`. Корректные имена моделей можно найти во вкладке «Подключение» в разделе AI Gateway.
    

Загруженный файл будет доступен только для модели, указанной в параметре `model`.

Пример ответа:

```js
{
 "id": "file-bGl0ZWxsbTpmaWxlLUdmMWRD1mDEZEtEOGZqQ1BBWjlxWk47bW9kZWwsb3BlbmFpL2dwdC00LjE7bGl0ZWxsbV9vd25lcl91c2VyX2lkLG50OTQ1NDI",
 "bytes": 27,
 "created_at": 1782804439,
 "filename": "testfile.txt",
 "object": "file",
 "purpose": "user_data",
 "status": "processed",
 "expires_at": null,
 "status_details": null
}
```

Для дальнейшей работы с файлом используйте значение поля `id`.

### Получение информации о файле

Метод позволяет получить метаданные загруженного файла:

```bash
curl --request GET \
 --url https://api.timeweb.ai/v1/files/<file_id> \
 --header "authorization: Bearer $TIMEWEB_AI_TOKEN"
```

Где `file_id` — идентификатор файла, полученный при загрузке.

### Получение содержимого файла

Метод `/content` реализован для совместимости с Files API и дальнейшего расширения сценариев работы с файлами:

```bash
curl --request GET \
 --url https://api.timeweb.ai/v1/files/<file_id>/content \
 --header "authorization: Bearer $TIMEWEB_AI_TOKEN"
```

Получение содержимого доступно только для подходящих значений purpose, например для сценариев `fine-tuning`. Такие сценарии сейчас не поддерживаются в AI Gateway. Для файлов с `purpose=user_data` или `purpose=messages` метод для чтения содержимого файла не используется.

### Удаление файла

Чтобы удалить файл, отправьте DELETE-запрос:

```bash
curl --request DELETE \
 --url https://api.timeweb.ai/v1/files/<file_id> \
 --header "authorization: Bearer $TIMEWEB_AI_TOKEN"
```

После удаления идентификатор файла нельзя использовать в запросах к модели.

## Пример работы с файлом

Рассмотрим пример с загрузкой текстового файла `test.txt`, который расположен по пути `/Users/timeweb_cloud/test.txt`.

```bash
curl --request POST \
 --url https://api.timeweb.ai/v1/files \
 --header "authorization: Bearer $TIMEWEB_AI_TOKEN" \
 --header "content-type: multipart/form-data" \
 --form purpose=user_data \
 --form "file=@/Users/timeweb_cloud/test.txt" \
 --form "target_model_names=openai/gpt-4.1"
```

В параметре `file` указан полный путь к файлу на локальном компьютере. Если файл находится в текущей директории терминала, можно указать относительный путь, например `file=@test.txt`.

Пример ответа:

```js
{
 "id": "file-bGl0ZWxsbTpmaWxlL87mMWRDV7NEZEtEOGZqQ1BBWjlxWk47bW9kZWwsb3BlbmFpL2dwdC00LjE7bGl0ZWxsbV9vd25lcl91c2VyX2lkLG50OTQ1NDI",
 "bytes": 27,
 "created_at": 1782804439,
 "filename": "test.txt",
 "object": "file",
 "purpose": "user_data",
 "status": "processed",
 "expires_at": null,
 "status_details": null
}
```

После загрузки файл можно передать модели в Responses API. Для этого в запросе используется объект с типом `input_file`, а в поле `file_id` передается идентификатор из ответа на загрузку:

```shell
curl https://api.timeweb.ai/v1/responses \
 --header "Content-Type: application/json" \
 --header "Authorization: Bearer $TIMEWEB_AI_TOKEN" \
 --data '{
   "model": "openai/gpt-4.1",
   "input": [
     {
       "role": "user",
       "content": [
         {
           "type": "input_text",
           "text": "Прочитай загруженный файл и кратко перескажи, что в нем написано."
         },
         {
           "type": "input_file",
           "file_id": "file-bGl0ZWxsbTpmaWxlL87mMWRDV7NEZEtEOGZqQ1BBWjlxWk47bW9kZWwsb3BlbmFpL2dwdC00LjE7bGl0ZWxsbV9vd25lcl91c2VyX2lkLG50OTQ1NDI"
         }
       ]
     }
   ]
 }'
```

Модель в запросе должна совпадать с моделью, для которой файл был загружен.