Files API в AI Gateway

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

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

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

Для работы с Files API нужен API-ключ AI Gateway. Создать ключ можно в разделе «AI-агенты» во вкладке «AI Gateway» → «API-ключи».

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

    

      

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

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

Методы API

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

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

    

      

    
    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.

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

    

      

    
    {
 "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.

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

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

    

      

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

  

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

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

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

    

      

    
    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-запрос:

    

      

    
    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.

    

      

    
    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.

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

    

      

    
    {
 "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 передается идентификатор из ответа на загрузку:

    

      

    
    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"
         }
       ]
     }
   ]
 }'

  

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