Документация API

Как получить API-ключ

Войдите в аккаунт, откройте личный кабинет и перейдите на вкладку API. Там показан ваш ключ и есть кнопка Создать заново. После перегенерации старый ключ сразу перестаёт работать, поэтому сначала обновите его везде, где он используется.

На этой вкладке есть и второй, независимый ключ только для загрузки. О том, когда его использовать вместо основного, читайте в подсказке ниже и в разделе Плагины для форумов.

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

Передавайте ключ в заголовке. Это предпочтительный способ, ведь строки запроса часто попадают в журналы доступа, журналы прокси и заголовки Referer:

X-API-Key: YOUR_API_KEY

Параметр запроса ?key= тоже работает: он оставлен для совместимости со старыми интеграциями и быстрых разовых команд curl. Если указаны оба способа, приоритет у заголовка.

?key=YOUR_API_KEY

Эндпоинты

Загрузка, просмотр списка и удаление используют одну и ту же аутентификацию и лимиты; большие файлы можно сначала отправить по частям.

POST /api: загрузка файла

Загружает один файл для авторизованного аккаунта.

Допустимые типы: изображения JPG, PNG, GIF, WEBP, AVIF, BMP, TIFF, HEIC или HEIF; видео MP4, WEBM или AVI (точный список может со временем расшириться). HEIC/HEIF и TIFF сохраняются как WebP, видео в форматах, отличных от MP4/WebM, конвертируется в MP4, а крупные изображения JPEG/PNG вскоре после загрузки конвертируются в WebP, если это заметно уменьшает их размер. Максимальный размер: 200 МБ; слишком большие или нечитаемые файлы отклоняются с ошибкой 422.

Ответ: 200 OK:

{
  "type": "success",
  "msg": "success",
  "data": {
    "id": "aB3xY9qRz1",
    "type": "image",
    "path": "https://i.yourimageshare.com/aB3xY9qRz1.png",
    "src": "https://yourimageshare.com/ib/aB3xY9qRz1.png",
    "direct": "https://yourimageshare.com/ib/aB3xY9qRz1",
    "thumb": "https://i.yourimageshare.com/thumb-aB3xY9qRz1.webp",
    "width": 1920,
    "height": 1080,
    "size": 482113,
    "locked": false,
    "visibility": "unlisted",
    "title": null,
    "description": null,
    "expires_at": null,
    "duplicate": false,
    "delete_url": "https://yourimageshare.com/delete#iV3x...k9"
  }
}

POST /api/chunk: большие файлы

Один запрос может нести не более 100 МБ. Для файлов побольше (до 200 МБ) или чтобы запросы оставались небольшими при медленном соединении, отправляйте файл частями не более 5 МБ, а затем завершите загрузку запросом POST /api:

1. Выберите идентификатор загрузки: 32 случайных шестнадцатеричных символа.
2. Для каждой части отправьте POST /api/chunk (multipart/form-data) с upload_id, index (с нуля), total (число частей) и байтами в chunk. Ответ: {"type": "success", "chunk_size": 5242880}.
3. Отправьте POST /api с upload_id и filename вместо uploads, а также с любыми другими полями загрузки. Ответ такой же, как при обычной загрузке.

Части незавершённой загрузки удаляются через 2 часа. К лимитам загрузки относится только завершающий POST /api.

GET /api/{id} и PATCH /api/{id}: одна загрузка

GET возвращает одну из ваших загрузок с теми же полями, что и в списке ниже. PATCH меняет её visibility, title или description (поля формы или JSON; пустое название или описание очищает значение) и возвращает обновлённую загрузку. Для обоих нужен полный API-ключ; если такой загрузки в вашем аккаунте нет, вернётся 404.

curl -X PATCH https://yourimageshare.com/api/aB3xY9qRz1 \
  -H "X-API-Key: YOUR_API_KEY" -d visibility=public -d title="Sunset"

POST /api/{id}/replace: замена файла

Подменяет файл в одной из ваших загрузок, сохраняя её id, страницу и все ссылки. Подойдёт любой допустимый тип, даже другой (изображение может стать видео). Отправьте новый файл как uploads (или upload_id файла, отправленного по частям через POST /api/chunk); keep_original работает так же, как при загрузке. Новый файл проходит те же проверки и конвертации, что и новая загрузка, а предыдущая версия удаляется. Нужен полный API-ключ; 404, если такой загрузки в вашем аккаунте нет, и 409, если она защищена паролем или ограничена по просмотрам.

curl -X POST https://yourimageshare.com/api/aB3xY9qRz1/replace \
  -H "X-API-Key: YOUR_API_KEY" -F [email protected]

GET /api: список ваших загрузок

Возвращает постраничный список загрузок авторизованного аккаунта (из любого источника: API, сайт или редактор), сначала новые, по 50 на страницу.

Ответ: 200 OK:

{
  "type": "success",
  "data": [
    {
      "id": "aB3xY9qRz1",
      "type": "image",
      "title": null,
      "path": "https://i.yourimageshare.com/aB3xY9qRz1.webp",
      "src": "https://yourimageshare.com/ib/aB3xY9qRz1.webp",
      "direct": "https://yourimageshare.com/ib/aB3xY9qRz1",
      "thumb": "https://i.yourimageshare.com/thumb-aB3xY9qRz1.webp",
      "width": 1920,
      "height": 1080,
      "size": 482113,
      "locked": false,
      "visibility": "unlisted",
      "description": null,
      "expires_at": null,
      "created_at": "2026-07-23T15:43:28+01:00"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

Поля здесь означают то же, что и в ответе на загрузку выше (для загрузки, защищённой паролем, path и thumb это недолговечные подписанные ссылки). Отдельного эндпоинта «получить одну загрузку» пока нет, поэтому этот список также позволяет потом найти id файла.

DELETE /api/{id}: удаление загрузки

Безвозвратно удаляет одну из загрузок авторизованного аккаунта. Через API это нельзя отменить. {id} — значение, которое возвращается как id в эндпоинтах загрузки и списка.

Ответ: 200 OK:

{ "type": "success", "msg": "Deleted." }

404, если в вашем аккаунте нет загрузки с таким id (она либо никогда вам не принадлежала, либо уже удалена).

Лимиты запросов

У каждого API-ключа есть независимые квоты в минуту и в сутки, а также более грубый суточный потолок на IP-адрес — защита от случая, когда один IP перебирает несколько ключей. Загрузки, списки и удаления используют общие лимиты.

Эти лимиты могут меняться. Каждый ответ содержит стандартные заголовки лимитов:

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 14

При превышении лимита возвращается 429 с заголовком Retry-After, в котором указано, сколько секунд нужно подождать.

Ошибки

Все ответы с ошибкой имеют одинаковый вид независимо от эндпоинта и причины:

{ "type": "error", "errors": "A human-readable description of what went wrong." }

Клиентские библиотеки

Официальные SDK, которые оборачивают описанные выше эндпоинты, возвращают типизированные результаты и выбрасывают исключения при ошибках API, избавляя вас от работы с «сырым» HTTP.

JavaScript / TypeScript

Без зависимостей, работает в Node.js и браузерах. Также есть в JSR как @yourimageshare/yourimageshare — npx jsr add @yourimageshare/yourimageshare — тот же исходный код, опубликованный сразу как TypeScript.

npm install yourimageshare

Python

Одна зависимость (requests), Python 3.8+.

pip install yourimageshare

PHP

Без зависимостей Composer (используется собственное расширение curl в PHP), PHP 7.4+. Исходный код на GitHub.

composer require yourimageshare/yourimageshare-php

Go

Без зависимостей (только стандартная библиотека), Go 1.18+. Полную справку смотрите на pkg.go.dev.

go get github.com/yourimageshare/yourimageshare/go

Rust

Две зависимости (ureq для блокирующего HTTP, без асинхронной среды выполнения, и serde), Rust 1.70+. Исходный код на GitHub.

cargo add yourimageshare

Ruby

Без зависимостей от гемов (стандартные Net::HTTP и json), Ruby 2.7+. Исходный код на GitHub.

gem install yourimageshare

.NET

Одна зависимость (собственный пакет Microsoft System.Text.Json), целевая платформа netstandard2.0, поэтому работает и в .NET Framework, и в современном .NET. Исходный код на GitHub. Собрано и проверено на этом действующем API; публикация в NuGet скоро.

dotnet add package YourImageShare

Dart / Flutter

Одна зависимость (http, пакет от самой команды Dart), Dart 2.17+. Исходный код на GitHub. Собрано и проверено на этом действующем API; публикация на pub.dev скоро.

dart pub add yourimageshare

Elixir

Одна зависимость (Req), Elixir 1.14+. Возвращает кортежи {:ok, result}| {:error, reason} — прямой аналог обработки ошибок этого API в остальных SDK — а также варианты с восклицательным знаком, которые выбрасывают исключения. Исходный код на GitHub, документация на HexDocs.

{:yourimageshare, "~> 1.1"}

MCP-сервер

Для ИИ-агентов, пишущих код (Claude Code, Cursor и другие инструменты, совместимые с MCP): вставляйте скриншот в отчёт об ошибке, описание PR или обращение в поддержку в виде обычной ссылки, а не base64-блока или ручной загрузки. Так же работает с Claude Desktop и любым другим MCP-клиентом. Запускается напрямую через npx, без установки:

npx yourimageshare-mcp

Инструменты: upload_image (локальный файл, встроенное содержимое или ссылка, до 200 МБ, с необязательными параметрами видимости, названия и автоудаления), list_uploads, get_upload, update_upload и delete_upload.

Также доступен в официальном реестре MCP (как io.github.yourimageshare/yourimageshare) и в каталогах Smithery и Glama, если ваш MCP-клиент устанавливает серверы оттуда.

Впервые слышите про MCP? Подробную инструкцию по настройке смотрите в статье как подключить Claude и ChatGPT к этому API через MCP.

Примеры кода

curl

# Upload a file
curl "https://yourimageshare.com/api" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "uploads=@/path/to/photo.jpg"

# Upload from a link (files up to 200MB; one direct upload request stops at 100MB -
# bigger files go in pieces, see Large Files above)
curl "https://yourimageshare.com/api" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "url=https://example.com/video.mp4"

# Upload a file that auto-deletes after 1 hour
curl "https://yourimageshare.com/api" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "uploads=@/path/to/photo.jpg" \
  -F "expires_in=3600"

# List uploads
curl "https://yourimageshare.com/api" -H "X-API-Key: YOUR_API_KEY"

# Upload a file without a page of its own (file only) and give it a title
curl "https://yourimageshare.com/api" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "uploads=@/path/to/photo.jpg" \
  -F "visibility=private" \
  -F "title=Sunset"

# Look up one upload, then make it public
curl "https://yourimageshare.com/api/aB3xY9qRz1" -H "X-API-Key: YOUR_API_KEY"
curl -X PATCH "https://yourimageshare.com/api/aB3xY9qRz1" \
  -H "X-API-Key: YOUR_API_KEY" -d "visibility=public"

# Delete an upload
curl -X DELETE "https://yourimageshare.com/api/aB3xY9qRz1" -H "X-API-Key: YOUR_API_KEY"

JavaScript (fetch)

const API_KEY = 'YOUR_API_KEY';
const BASE = 'https://yourimageshare.com/api';

async function uploadFile(file) {
  const form = new FormData();
  form.append('uploads', file);

  const res = await fetch(BASE, {
    method: 'POST',
    headers: { 'X-API-Key': API_KEY },
    body: form,
  });
  const json = await res.json();
  if (json.type !== 'success') throw new Error(json.errors);
  return json.data;
}

async function listUploads(page = 1) {
  const res = await fetch(`${BASE}?page=${page}`, {
    headers: { 'X-API-Key': API_KEY },
  });
  return res.json();
}

async function deleteUpload(id) {
  const res = await fetch(`${BASE}/${id}`, {
    method: 'DELETE',
    headers: { 'X-API-Key': API_KEY },
  });
  return res.json();
}

Python (requests)

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://yourimageshare.com/api"

HEADERS = {"X-API-Key": API_KEY}

# Upload a file
with open("/path/to/photo.jpg", "rb") as f:
    res = requests.post(BASE, headers=HEADERS, files={"uploads": f})
res.raise_for_status()
upload = res.json()["data"]

# List uploads
res = requests.get(BASE, headers=HEADERS, params={"page": 1})
uploads = res.json()

# Delete an upload
res = requests.delete(f"{BASE}/{upload['id']}", headers=HEADERS)

PHP (curl)

<?php

$apiKey = 'YOUR_API_KEY';
$base = 'https://yourimageshare.com/api';

// Upload a file
$curl = curl_init($base);
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: $apiKey"],
    CURLOPT_POSTFIELDS => ['uploads' => new CURLFile('/path/to/photo.jpg')],
    CURLOPT_RETURNTRANSFER => true,
]);
$upload = json_decode(curl_exec($curl), true)['data'];
curl_close($curl);

// List uploads
$curl = curl_init("$base?page=1");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-API-Key: $apiKey"]);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$uploads = json_decode(curl_exec($curl), true);
curl_close($curl);

Go (net/http)

Официальный Go SDK выше делает всё это за вас — этот «сырой» вариант приведён для тех, кто не хочет добавлять зависимость.

package main

import (
    "bytes"
    "encoding/json"
    "io"
    "mime/multipart"
    "net/http"
    "os"
)

const apiKey = "YOUR_API_KEY"
const base = "https://yourimageshare.com/api"

func uploadFile(path string) (map[string]any, error) {
    file, err := os.Open(path)
    if err != nil {
        return nil, err
    }
    defer file.Close()

    body := &bytes.Buffer{}
    writer := multipart.NewWriter(body)
    part, _ := writer.CreateFormFile("uploads", path)
    io.Copy(part, file)
    writer.Close()

    req, _ := http.NewRequest("POST", base, body)
    req.Header.Set("Content-Type", writer.FormDataContentType())
    req.Header.Set("X-API-Key", apiKey)

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer res.Body.Close()

    var result map[string]any
    json.NewDecoder(res.Body).Decode(&result)
    return result, nil
}

Инструменты для скриншотов

Расширение для браузера, а также готовые конфиги и скрипты, которые отправляют скриншоты прямо на YourImageShare без ручной загрузки. Каждый из них загружает файлы через тот же эндпоинт /api, что описан выше.

Расширение для браузера (Chrome и Firefox)

Расширение YourImageShare Capture для Chrome и Firefox обходится без скриптов и файлов конфигурации. Оно снимает видимую область, выделенный мышью фрагмент или всю прокручиваемую страницу, открывает встроенный редактор со стрелками, текстом, размытием/скрытием и другими аннотациями, а затем скачивает результат, копирует его в буфер обмена или публикует прямо на YourImageShare одним щелчком. Публикация использует тот же эндпоинт /api, что описан выше: один раз добавьте API-ключ в настройках расширения, и каждая следующая публикация сразу выдаёт ссылку, которой можно поделиться. Работает в Chrome для компьютера (и других браузерах на Chromium), Firefox для компьютера и Firefox для Android.

Установить YourImageShare Capture для Firefox Установить YourImageShare Capture для Chrome

ShareX

Скачайте пользовательский загрузчик ниже, затем в ShareX откройте Destinations > Custom uploader settings > Import > from file, выберите скачанный файл .sxcu и замените YOUR_API_KEY в поле Headers своим настоящим ключом. Назначьте его местом загрузки изображений/файлов, и снимки будут загружаться автоматически.

Скачать YourImageShare.sxcu

Flameshot (Linux)

Небольшой shell-скрипт, который запускает flameshot gui, загружает снимок и копирует ссылку в буфер обмена. Привяжите его к сочетанию клавиш в вашем окружении рабочего стола вместо стандартного сочетания Flameshot.

Скачать yis-flameshot-upload.sh

# One-time setup
chmod +x yis-flameshot-upload.sh
export YIS_API_KEY="YOUR_API_KEY"   # or add to ~/.config/yourimageshare/api_key

# Then bind this to a hotkey instead of calling flameshot directly:
/path/to/yis-flameshot-upload.sh

Greenshot (Windows)

Скрипт PowerShell для встроенного места назначения Greenshot External command. Совместим с Windows PowerShell 5.1, который входит в состав Windows, дополнительная установка не нужна.

Скачать yis-greenshot-upload.ps1

# One-time setup
setx YIS_API_KEY "YOUR_API_KEY"

# In Greenshot: Preferences > Destinations > External command > Settings
#   Command:   powershell.exe
#   Arguments: -ExecutionPolicy Bypass -File "C:\path\to\yis-greenshot-upload.ps1" "%1"

Плагины для форумов

Добавьте настоящую кнопку «Загрузить изображение» рядом с редактором сообщений на вашем форуме. Каждый плагин загружает файлы через тот же эндпоинт /api, что описан выше, и вставляет BBCode в позицию курсора: без отдельной вкладки и ручного копирования.

Загрузки с форума по умолчанию приватные: изображение работает в сообщении, но YourImageShare не создаёт для него отдельную страницу (без комментариев, реакций и рекламы). В каждом плагине есть настройка переключения на unlisted, если вам нужна ещё и страница для всех, у кого есть ссылка.

phpBB

Полноценное расширение для phpBB 3.2/3.3. Распакуйте в ext/, включите его в разделе Customise > Manage extensions, затем замените YOUR_UPLOAD_ONLY_KEY в файле событий шаблона расширения своим настоящим ключом только для загрузки.

Скачать для phpBB

SMF (Simple Machines Forum)

Полноценный пакет для SMF: установите его через Admin > Package Manager, затем замените YOUR_UPLOAD_ONLY_KEY в Sources/yis_forumupload.php своим настоящим ключом только для загрузки.

Скачать для SMF

MyBB

Полноценный плагин для MyBB 1.8. Скопируйте в inc/plugins/, активируйте в разделе Configuration > Plugins, затем замените YOUR_UPLOAD_ONLY_KEY в файле плагина своим настоящим ключом только для загрузки.

Скачать для MyBB

FluxBB, PunBB и ZetaBoards

В них нет формальной системы плагинов, поэтому это небольшой фрагмент кода, который вставляется прямо в шаблон (FluxBB/PunBB) или в панель администратора (ZetaBoards). Подробные инструкции для каждого:

Инструкция для FluxBB Инструкция для PunBB Инструкция для ZetaBoards

Плагин для WordPress

Переносите медиатеку на YourImageShare вместо локального диска. Новые изображения и видео автоматически загружаются через тот же эндпоинт /api, что описан выше, локальный файл (и все сгенерированные размеры миниатюр) удаляется после подтверждения загрузки, а все адреса вложений WordPress — в блочном редакторе, миниатюрах записей, галереях, REST API — ведут на файл, размещённый на YourImageShare. Без шорткодов и изменений в привычной работе.

• Массовый перенос уже существующей медиатеки в фоновом режиме (или командой wp yis offload --all), а не только новых загрузок
• Изображения и видео, уже вставленные в записи, продолжают работать после удаления локальных файлов
• Миниатюры и srcset используют нашу миниатюру шириной 280px, поэтому в небольших блоках не загружаются файлы полного размера
• Файлы до 200 МБ отправляются по частям, так что большие видео не перегружают виртуальный хостинг
• Любой перенесённый файл можно в любой момент вернуть в локальное хранилище
• Столбец в медиатеке показывает, что перенесено, а что ещё хранится локально
• Перенесённые файлы хранятся как приватные: они загружаются везде, где их использует ваш сайт, но не получают собственной страницы на YourImageShare

Получить на WordPress.org Скачать ZIP

В WordPress: Плагины > Добавить новый, найдите YourImageShare Media Offload, затем нажмите «Установить» и «Активировать».

Из блога