> ## Documentation Index
> Fetch the complete documentation index at: https://speshu.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Список файлов

> GET /api/v1/storage — постраничный список файлов хранилища с фильтрами

Возвращает файлы вашего хранилища, от новых к старым. Есть фильтр по типу и полнотекстовый поиск по имени. Удалённые и архивные файлы в выдаче не появляются.

## Пример

<CodeGroup>
  ```bash cURL theme={null} theme={null}
  curl "https://speshu.ai/api/v1/storage?limit=20&type=chat_upload" \
    -H "Authorization: Bearer $SPESHU_API_KEY"
  ```

  ```python Python theme={null} theme={null}
  import requests

  response = requests.get(
      "https://speshu.ai/api/v1/storage",
      headers={"Authorization": "Bearer sk-ваш-ключ"},
      params={"limit": 20, "type": "chat_upload", "search": "счёт"},
  )

  data = response.json()
  print(data["total"], "всего")
  for asset in data["assets"]:
      print(asset["created_at"], asset["filename"], asset["url"])
  ```
</CodeGroup>

## Параметры

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `limit` | integer | 50 | Сколько файлов вернуть. Максимум 100 |
| `offset` | integer | 0 | Сколько файлов пропустить |
| `type` | string | — | Фильтр по типу. Неизвестное значение молча игнорируется |
| `search` | string | — | Полнотекстовый поиск по имени файла |

<Info>
  Пагинация — только `limit` и `offset`. Ни `page`, ни `totalPages`, ни курсора здесь нет.
</Info>

Допустимые значения `type`:

`chat_upload`, `reference_image`, `generated_image`, `generated_video`, `generated_audio`, `generated_document`, `voice_message`, `avatar`, `invoice_pdf`.

<Note>
  Осмысленны как типы загрузки только `chat_upload`, `reference_image` и `voice_message` — это то, что создаёт эндпоинт загрузки. Остальные значения существуют в фильтре, но появляются из других источников: генерации медиа и служебных операций.
</Note>

## Ответ

`200 OK`:

```json theme={null} theme={null}
{
  "assets": [
    {
      "id": "0199...",
      "filename": "photo.png",
      "url": "https://cdn.example.com/uploads/1/2026/10/02/0199....png",
      "asset_type": "chat_upload",
      "size": 245760,
      "mime_type": "image/png",
      "created_at": "2026-10-02T12:31:04Z",
      "session_id": "sess_123"
    }
  ],
  "total": 1
}
```

| Поле | Тип | Описание |
| - | - | - |
| `assets` | array | Файлы текущей страницы, от новых к старым |
| `assets[].id` | string | Идентификатор файла |
| `assets[].filename` | string | Имя файла |
| `assets[].url` | string | Публичная ссылка на файл |
| `assets[].asset_type` | string | Тип файла |
| `assets[].size` | integer | Размер сохранённого файла в байтах |
| `assets[].mime_type` | string | Тип сохранённого файла |
| `assets[].created_at` | string | Дата и время в формате `YYYY-MM-DDTHH:MM:SSZ` |
| `assets[].session_id` | string | Идентификатор сессии. Может отсутствовать |
| `total` | integer | Сколько файлов подходит под фильтр **по всем страницам** |

<Warning>
  `total` — это не длина текущей страницы. Это счётчик по всему фильтру, поэтому по нему можно посчитать число страниц: `ceil(total / limit)`.
</Warning>

<Note>
  `session_id` приходит не у всех файлов: у загруженных без него он пуст или отсутствует.
</Note>

## Что дальше

<CardGroup cols={2}>
  <Card title="Загрузить файл" icon="upload" href="/docs/api-reference/storage/upload">
    Положить файл в хранилище
  </Card>

  <Card title="Метаданные файла" icon="magnifying-glass" href="/docs/api-reference/storage/get">
    Один файл по идентификатору
  </Card>

  <Card title="Удалить файл" icon="trash" href="/docs/api-reference/storage/delete">
    Убрать файл из хранилища
  </Card>

  <Card title="Ошибки" icon="triangle-exclamation" href="/docs/errors">
    Полная таблица кодов
  </Card>
</CardGroup>


## OpenAPI

````yaml api-reference/openapi.json GET /api/v1/storage
openapi: 3.1.0
info:
  title: SpeShu.AI API
  version: 1.0.0
  description: >-
    Единый OpenAI-совместимый API для текстовых моделей, генерации изображений,
    видео, аудио и музыки.


    ## Аутентификация


    Все запросы, кроме `GET /api/v1/models` и `GET /api/v1/media/models`,
    требуют API-ключ. Ключ передаётся в заголовке `Authorization: Bearer <ключ>`
    или `X-Api-Key: <ключ>`.


    ## Ошибки


    Текстовые эндпоинты (`/chat/completions`, `/responses`, `/messages`) и
    `/balance` возвращают ошибки в формате OpenAI:


    ```json

    { "error": { "message": "...", "type": "invalid_request_error", "param":
    null, "code": "invalid_request" } }

    ```


    Эндпоинты медиа используют собственный конверт:


    ```json

    { "code": 422, "msg": "...", "data": null }

    ```


    Подробности — на странице [Ошибки](/errors).
servers:
  - url: https://speshu.ai
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Текст
    description: Генерация текста и диалог
  - name: Медиа
    description: Асинхронные задачи генерации изображений, видео, аудио и музыки
  - name: Хранилище
    description: Файлы пользователя
  - name: Справочник
    description: Каталог моделей и баланс
paths:
  /api/v1/storage:
    get:
      tags:
        - Хранилище
      summary: Список файлов
      operationId: listFiles
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: type
          in: query
          schema:
            type: string
            enum:
              - chat_upload
              - reference_image
              - generated_image
              - generated_video
              - generated_audio
              - generated_document
              - voice_message
              - avatar
              - invoice_pdf
          description: Фильтр по типу. Неизвестное значение игнорируется.
        - name: search
          in: query
          schema:
            type: string
          description: Полнотекстовый поиск по имени файла.
      responses:
        '200':
          description: Список файлов.
          content:
            application/json:
              schema:
                type: object
                properties:
                  assets:
                    type: array
                    items:
                      $ref: '#/components/schemas/AssetSummary'
                  total:
                    type: integer
                    description: Всего файлов по фильтру, без учёта страницы.
                required:
                  - assets
                  - total
        '401':
          $ref: '#/components/responses/OpenAIError'
        '500':
          $ref: '#/components/responses/StorageError'
components:
  schemas:
    AssetSummary:
      type: object
      properties:
        id:
          type: string
        filename:
          type: string
        url:
          type: string
        asset_type:
          type: string
        size:
          type: integer
        mime_type:
          type: string
        created_at:
          type: string
        session_id:
          type: string
      required:
        - id
        - filename
        - url
    OpenAIError:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
              examples:
                - invalid_request_error
              description: >-
                `authentication_error` при 401, `rate_limit_error` при 429,
                `permission_error` при 403, в остальных случаях
                `invalid_request_error`, `api_error` или `internal_error`.
            param:
              type:
                - string
                - 'null'
            code:
              type:
                - string
                - 'null'
              examples:
                - invalid_request
              description: >-
                Машиночитаемый код: `invalid_api_key`, `unauthorized`,
                `insufficient_quota`, `rate_limit_exceeded`,
                `token_limit_exceeded`, `content_too_large`, `limit_exceeded`,
                `model_not_found`, `no_providers`, `service_unavailable`,
                `provider_error`, `invalid_request`, `context_length_exceeded`,
                `internal_error`.
          required:
            - message
            - type
      required:
        - error
    StorageError:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
              examples:
                - invalid_request
          required:
            - message
            - type
      required:
        - error
  responses:
    OpenAIError:
      description: Ошибка в формате OpenAI.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAIError'
    StorageError:
      description: Ошибка хранилища.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StorageError'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        API-ключ в формате `sk-...`. Альтернативно — заголовок `X-Api-Key:
        sk-...` (совместимо с Anthropic SDK).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.