> ## 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/{id} — метаданные одного файла и ссылка на него

Возвращает метаданные одного файла и публичную ссылку на него. Сами байты здесь не отдаются — забирайте их по полю `url`.

## Пример

<CodeGroup>
  ```bash cURL theme={null} theme={null}
  curl https://speshu.ai/api/v1/storage/0199abc-... \
    -H "Authorization: Bearer $SPESHU_API_KEY"
  ```

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

  response = requests.get(
      "https://speshu.ai/api/v1/storage/0199abc-...",
      headers={"Authorization": "Bearer sk-ваш-ключ"},
  )

  asset = response.json()["asset"]
  print(asset["filename"], asset["size_bytes"], asset["status"])

  # Байты лежат по ссылке, а не в этом ответе.
  blob = requests.get(asset["url"])
  print(len(blob.content), "байт")
  ```
</CodeGroup>

## Ответ

`200 OK`:

```json theme={null} theme={null}
{
  "asset": {
    "id": "0199...",
    "filename": "photo.png",
    "storage_key": "uploads/1/2026/10/02/0199....png",
    "asset_type": "chat_upload",
    "mime_type": "image/png",
    "extension": ".png",
    "size_bytes": 245760,
    "status": "active",
    "source": "user_upload",
    "created_at": "2026-10-02T12:31:04Z",
    "updated_at": "2026-10-02T12:31:04Z",
    "url": "https://cdn.example.com/uploads/1/2026/10/02/0199....png"
  }
}
```

| Поле | Тип | Описание |
| - | - | - |
| `id` | string | Идентификатор файла |
| `filename` | string | Имя файла |
| `storage_key` | string | Внутренний ключ хранения — для диагностики, не для построения ссылок |
| `asset_type` | string | Тип файла |
| `mime_type` | string | Тип сохранённого файла |
| `extension` | string | Расширение с точкой |
| `size_bytes` | integer | Размер сохранённого файла в байтах |
| `status` | string | `pending`, `active`, `archived` или `deleted` |
| `source` | string | `user_upload`, `ai_generation`, `import` или `system` |
| `created_at` | string | Дата и время в формате `YYYY-MM-DDTHH:MM:SSZ` |
| `updated_at` | string | Дата и время последнего изменения |
| `url` | string | Публичная ссылка на файл |

## Как получить сам файл

<Warning>
  Этот эндпоинт отдаёт только метаданные. Отдельных маршрутов `/content` и `/download` у `/api/v1/storage/{id}` нет — ни такого ответа на скачивание, ни переадресации.
</Warning>

Байты лежат по полю `url`:

```bash cURL theme={null} theme={null}
curl -O "https://cdn.example.com/uploads/1/2026/10/02/0199....png"
```

Ссылка публичная и бессрочная. Если нужен файл в виде ответа со своими заголовками, скачайте файл сами и отдайте своим клиентам.

## Чужие файлы

<Warning>
  Файл, принадлежащий другому пользователю, возвращает `404`, а не `403`. Это сделано намеренно: по коду ответа нельзя определить, что идентификатор существует, но принадлежит кому-то другому.
</Warning>

## Ошибки

| Код | Причина |
| - | - |
| `401` | Ключ не передан или недействителен |
| `404` | Файл не найден, удалён или принадлежит другому пользователю |
| `500` | Внутренняя ошибка |

<Info>
  Формат тела ошибки здесь такой же, как у остальных эндпоинтов хранилища: `{"error": {"message": "...", "type": "invalid_request"}}` — без полей `param` и `code`, которые есть у OpenAI-формата. Подробности — на странице [Ошибки](/docs/errors).
</Info>

## Что дальше

<CardGroup cols={2}>
  <Card title="Список файлов" icon="list" href="/docs/api-reference/storage/list">
    Что уже лежит в хранилище
  </Card>

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

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

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


## OpenAPI

````yaml api-reference/openapi.json GET /api/v1/storage/{id}
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/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Хранилище
      summary: Метаданные файла
      description: >-
        Возвращает метаданные файла и ссылку на него. Сами байты здесь не
        отдаются — забирайте их по `url`.
      operationId: getFile
      responses:
        '200':
          description: Метаданные файла.
          content:
            application/json:
              schema:
                type: object
                properties:
                  asset:
                    type: object
                    properties:
                      id:
                        type: string
                      filename:
                        type: string
                      storage_key:
                        type: string
                      asset_type:
                        type: string
                      mime_type:
                        type: string
                      extension:
                        type: string
                      size_bytes:
                        type: integer
                      status:
                        type: string
                        enum:
                          - pending
                          - active
                          - archived
                          - deleted
                      source:
                        type: string
                        enum:
                          - user_upload
                          - ai_generation
                          - import
                          - system
                      created_at:
                        type: string
                      updated_at:
                        type: string
                      url:
                        type: string
                    required:
                      - id
                      - filename
                      - url
                required:
                  - asset
        '401':
          $ref: '#/components/responses/OpenAIError'
        '404':
          $ref: '#/components/responses/StorageError'
        '500':
          $ref: '#/components/responses/StorageError'
components:
  responses:
    OpenAIError:
      description: Ошибка в формате OpenAI.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAIError'
    StorageError:
      description: Ошибка хранилища.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StorageError'
  schemas:
    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
  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.