KAR.SU / Инструменты

Загрузка файлов через API

Подключите KAR.SU к своему приложению или скрипту. Отправьте файл — получите прямую ссылку и адрес страницы просмотра.

API v1.1POST · JSON

Подключайте свои приложенияЗагрузка по HTTPS · API v1.1

Начните с одного запроса

От файла до ссылки

Для загрузки используйте POST и передайте файл в поле source. Ответ по умолчанию приходит в формате JSON.

Адрес загрузки

POSThttps://www.kar.su/api/1/upload

Пример · cURL

curl --fail-with-body -X POST https://www.kar.su/api/1/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "source=@image.jpg" \
  -F "title=Моё изображение"

Замените YOUR_API_KEY своим ключом, а image.jpg — путём к файлу. Пример рассчитан на Bash; в Windows можно использовать WSL.

01Получите ключОткройте раздел API в настройках аккаунта.
02Отправьте файлПередайте ключ в заголовке, а файл — в теле запроса.
03Заберите ссылкуИспользуйте image.url из ответа сервера.

Доступ к API

Ключ и авторизация

Ваш ключ находится в настройках аккаунта → API. Передавайте его в заголовке X-API-Key.

Заголовок запроса

X-API-Key: YOUR_API_KEY

Открыть настройки API

Храните личный ключ на сервере. Не вставляйте его в публичный JavaScript, открытые репозитории или сообщения.

API также принимает GET-запросы и параметр key. Для обычной загрузки рекомендуем POST и заголовок: так ключ не попадает в адрес запроса.

Настройка загрузки

Параметры запроса

Обязателен файл в поле source и действующий ключ. Остальные параметры добавляйте по необходимости.

Параметр	Что передать
`source`Обязательно	Файл, строка Base64 или URL изображения.
`key`Вместо заголовка	Ключ API, если невозможно передать `X-API-Key`.
`title`	Название файла. Если не указано, определяется из метаданных.
`description`	Описание файла. Если не указано, определяется из метаданных.
`tags`	Теги через запятую: `природа,путешествия`.
`album_id`	Идентификатор альбома, принадлежащего владельцу ключа.
`category_id`	Идентификатор категории для загружаемого файла.
`width`	Желаемая ширина изображения. Высота рассчитывается автоматически.
`expiration`	Интервал до автоматического удаления: `PT5M` — 5 минут, `P3D` — 3 дня.
`nsfw`	Отметка контента для взрослых: `1` — включена, `0` — выключена.
`format`	Формат ответа: `json`, `txt` или `redirect`.
`use_file_date`Только администратор	`1` — использовать дату съёмки из Exif вместо даты загрузки; `0` — дату загрузки.

Результат запроса

Ответ сервера

При успешной загрузке JSON содержит status_code: 200, status_txt: "OK" и объект image. Ниже — сокращённый пример; адреса в нём приведены для иллюстрации.

JSON · сокращённый пример

{
  "status_code": 200,
  "status_txt": "OK",
  "success": { "message": "file uploaded", "code": 200 },
  "image": {
    "title": "Моё изображение",
    "url": "https://kar.su/images/example.jpg",
    "url_viewer": "https://kar.su/image/example"
  }
}

Поле	Назначение
`image.url`	Прямая ссылка на загруженный файл.
`image.url_viewer`	Страница просмотра на KAR.SU.
`status_code`	Код результата обработки запроса.

Другие форматы ответа

format=txt возвращает прямую ссылку текстом. format=redirect перенаправляет на страницу загруженного файла.

Быстрая проверка

Если загрузка не прошла

Ошибка ключа или доступа

Проверьте ключ в настройках аккаунта и заголовок X-API-Key. Не добавляйте перед ключом слово Bearer. Для альбома используйте ключ его владельца.

Не передан файл

Поле должно называться source. В примере cURL символ @ перед путём означает отправку содержимого файла.

Неподходящий формат или размер

Проверьте формат файла и действующие ограничения загрузки для вашего аккаунта. Доступные форматы и лимит показаны в окне загрузки на сайте.

Нужны подробности ошибки

Запрашивайте format=json и смотрите тело ответа вместе с HTTP-кодом. Ключ --fail-with-body в примере cURL сохраняет текст ответа при ошибке.