API-Dokumentation

API-Schlüssel erhalten

Melde dich an, geh zu Mein Konto und öffne den Tab API. Dort siehst du deinen Schlüssel und einen Button Neu generieren. Wenn du einen Schlüssel neu generierst, wird der alte sofort ungültig – aktualisiere ihn also überall, wo du ihn verwendest, bevor du klickst.

In diesem Tab gibt es außerdem einen zweiten, unabhängigen Nur-Upload-Schlüssel – siehe den Tipp unten und Forum-Plugins, wann du ihn stattdessen verwenden solltest.

Authentifizierung

Sende deinen Schlüssel als Header – das ist die bevorzugte Variante, denn Query-Strings landen gern in Zugriffs- und Proxy-Logs und in Referer-Headern:

X-API-Key: YOUR_API_KEY

Ein Query-Parameter ?key= funktioniert ebenfalls; er bleibt aus Kompatibilitätsgründen für ältere Integrationen und schnelle einmalige curl-Befehle erhalten. Wenn beides vorhanden ist, hat der Header Vorrang.

?key=YOUR_API_KEY

Endpunkte

Hochladen, Auflisten und Löschen nutzen dieselbe Authentifizierung und dieselben Limits; große Dateien kannst du vorab in Teilen senden.

POST /api – Datei hochladen

Lädt eine einzelne Datei für das authentifizierte Konto hoch.

Erlaubte Typen: JPG, PNG, GIF, WEBP, AVIF, BMP, TIFF, HEIC oder HEIF-Bilder; MP4, WEBM oder AVI-Videos (die genaue Liste kann sich mit der Zeit erweitern). HEIC/HEIF und TIFF werden als WebP gespeichert, Videos außer MP4/WebM werden in MP4 umgewandelt, und größere JPEG/PNG-Bilder werden kurz nach dem Upload in WebP umgewandelt, wenn sie dadurch spürbar kleiner werden. Maximale Größe: 200MB; zu große oder nicht lesbare Dateien werden mit einem 422 abgelehnt.

Antwort – 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 – Große Dateien

Eine einzelne Anfrage kann höchstens 100MB enthalten. Bei größeren Dateien (bis 200MB) oder um jede Anfrage bei einer langsamen Verbindung klein zu halten, sendest du die Datei in Teilen von höchstens 5MB und schließt dann mit POST /api ab:

1. Wähle eine Upload-ID: 32 zufällige Hex-Zeichen.
2. Sende für jedes Teil POST /api/chunk (multipart/form-data) mit upload_id, index (ab 0), total (Anzahl der Teile) und den Bytes in chunk. Die Antwort lautet {"type": "success", "chunk_size": 5242880}.
3. Sende POST /api mit upload_id und filename statt uploads, plus beliebigen weiteren Upload-Feldern. Die Antwort ist die normale Upload-Antwort.

Teile eines nicht abgeschlossenen Uploads werden nach 2 Stunden gelöscht. Nur das abschließende POST /api zählt für die Upload-Limits.

GET /api/{id} und PATCH /api/{id} – Ein Upload

GET gibt einen deiner Uploads mit denselben Feldern wie in der Liste unten zurück. PATCH ändert visibility, title oder description (Formularfelder oder JSON; ein leerer Titel oder eine leere Beschreibung löscht den Wert) und antwortet mit dem aktualisierten Upload. Beides erfordert den vollständigen API-Schlüssel; 404, wenn es in deinem Konto keinen solchen Upload gibt.

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 – Datei ersetzen

Tauscht die Datei hinter einem deiner Uploads aus und behält dessen ID, Seite und alle Links. Jeder erlaubte Typ funktioniert, auch ein anderer (ein Bild kann zu einem Video werden). Sende die neue Datei als uploads (oder upload_id einer Datei, die mit POST /api/chunk in Teilen gesendet wurde); keep_original funktioniert wie beim Upload. Die neue Datei durchläuft dieselben Prüfungen und Umwandlungen wie ein neuer Upload, und die vorherige Version wird entfernt. Erfordert den vollständigen API-Schlüssel; 404, wenn es in deinem Konto keinen solchen Upload gibt, 409, wenn er passwortgeschützt oder auf eine bestimmte Anzahl Aufrufe begrenzt ist.

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

GET /api – Deine Uploads auflisten

Gibt eine seitenweise Liste der Uploads des authentifizierten Kontos zurück (aus jeder Quelle – API, Website oder Editor), die neuesten zuerst, 50 pro Seite.

Antwort – 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 }
}

Die Felder bedeuten hier dasselbe wie in der Upload-Antwort oben (bei einem passwortgeschützten Upload sind path und thumb kurzlebige, signierte Links). Einen eigenen Endpunkt, um „einen Upload abzurufen“, gibt es noch nicht, daher ist diese Liste auch der Weg, um die id einer Datei nachträglich herauszufinden.

DELETE /api/{id} – Upload löschen

Löscht einen Upload des authentifizierten Kontos dauerhaft. Über die API lässt sich das nicht rückgängig machen. {id} ist der Wert, der von den Endpunkten zum Hochladen oder Auflisten als id zurückgegeben wird.

Antwort – 200 OK:

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

404, wenn es in deinem Konto keinen Upload mit dieser ID gibt (entweder er gehörte nie dir oder wurde bereits gelöscht).

Limits

Jeder API-Schlüssel hat eigene Kontingente pro Minute und pro Tag, dazu eine gröbere Tagesgrenze pro IP als Absicherung dagegen, dass eine IP mehrere Schlüssel durchwechselt. Hochladen, Auflisten und Löschen teilen sich dieselben Limits.

Diese Limits können sich ändern. Jede Antwort enthält die üblichen Rate-Limit-Header:

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

Sobald ein Limit überschritten ist, kommt ein 429 zurück, mit einem Retry-After-Header, der dir sagt, wie viele Sekunden du warten musst.

Fehler

Jede Fehlerantwort hat dieselbe Form, unabhängig von Endpunkt oder Ursache:

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

Client-Bibliotheken

Offizielle SDKs, die die obigen Endpunkte mit typisierten Ergebnissen kapseln und bei API-Fehlern eine Exception auslösen, statt dass du rohes HTTP behandeln musst.

JavaScript / TypeScript

Keine Abhängigkeiten, funktioniert in Node.js und im Browser. Auch auf JSR als @yourimageshare/yourimageshare – npx jsr add @yourimageshare/yourimageshare – derselbe Quellcode, direkt als TypeScript veröffentlicht.

npm install yourimageshare

Python

Eine Abhängigkeit (requests), Python 3.8+.

pip install yourimageshare

PHP

Keine Composer-Abhängigkeiten (nutzt die PHP-eigene curl-Erweiterung), PHP 7.4+. Quellcode auf GitHub.

composer require yourimageshare/yourimageshare-php

Go

Keine Abhängigkeiten (nur Standardbibliothek), Go 1.18+. Die vollständige Referenz findest du auf pkg.go.dev.

go get github.com/yourimageshare/yourimageshare/go

Rust

Zwei Abhängigkeiten (ureq für blockierendes HTTP – ohne Async-Runtime – plus serde), Rust 1.70+. Quellcode auf GitHub.

cargo add yourimageshare

Ruby

Keine Gem-Abhängigkeiten (Stdlib Net::HTTP + json), Ruby 2.7+. Quellcode auf GitHub.

gem install yourimageshare

.NET

Eine Abhängigkeit (Microsofts eigenes System.Text.Json), zielt auf netstandard2.0, funktioniert also sowohl mit .NET Framework als auch mit modernem .NET. Quellcode auf GitHub. Gegen diese Live-API gebaut und geprüft; die Veröffentlichung auf NuGet folgt in Kürze.

dotnet add package YourImageShare

Dart / Flutter

Eine Abhängigkeit (http, das eigene Paket des Dart-Teams), Dart 2.17+. Quellcode auf GitHub. Gegen diese Live-API gebaut und geprüft; die Veröffentlichung auf pub.dev folgt in Kürze.

dart pub add yourimageshare

Elixir

Eine Abhängigkeit (Req), Elixir 1.14+. Gibt {:ok, result}| {:error, reason}-Tupel zurück – das direkte Gegenstück zur Fehlerbehandlung dieser API in allen anderen SDKs – plus Bang-Varianten, die eine Exception auslösen. Quellcode auf GitHub, Doku auf HexDocs.

{:yourimageshare, "~> 1.1"}

MCP-Server

Für KI-Coding-Agenten (Claude Code, Cursor und andere MCP-kompatible Tools) – füge einen Screenshot als echten Link in einen Bug-Report, eine PR-Beschreibung oder einen Support-Thread ein, statt als Base64-Blob oder über einen manuellen Upload-Schritt. Funktioniert genauso mit Claude Desktop und jedem anderen MCP-Client. Direkt mit npx starten, ganz ohne Installation:

npx yourimageshare-mcp

Tools: upload_image (eine lokale Datei, Inhalt direkt übergeben oder ein Link, bis 200MB, mit optionaler Sichtbarkeit, Titel und automatischem Löschen), list_uploads, get_upload, update_upload und delete_upload.

Auch in der offiziellen MCP Registry (als io.github.yourimageshare/yourimageshare) und bei Smithery und Glama gelistet, falls dein MCP-Client von dort installiert.

Neu bei MCP? In der Anleitung So verbindest du Claude und ChatGPT per MCP mit dieser API findest du eine vollständige Einrichtung Schritt für Schritt.

Codebeispiele

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)

Das offizielle Go-SDK oben übernimmt das für dich – diese Variante ohne SDK ist für alle gedacht, die die Abhängigkeit lieber nicht hinzufügen möchten.

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
}

Screenshot-Tools

Eine Browser-Erweiterung sowie fertige Konfigurationen und Skripte, um Screenshots direkt an YourImageShare zu senden, ganz ohne manuelles Hochladen. Jedes davon lädt über denselben /api-Endpunkt hoch, der oben dokumentiert ist.

Browser-Erweiterung (Chrome & Firefox)

Die Erweiterung YourImageShare Capture für Chrome und Firefox kommt ganz ohne Skripte und Konfigurationsdateien aus. Sie nimmt den sichtbaren Bereich, einen per Ziehen markierten Ausschnitt oder eine ganze scrollende Seite auf, öffnet einen integrierten Editor für Pfeile, Text, Weichzeichnen/Schwärzen und andere Anmerkungen und lädt das Ergebnis dann herunter, kopiert es in die Zwischenablage oder veröffentlicht es mit einem Klick direkt auf YourImageShare. Das Veröffentlichen nutzt denselben /api-Endpunkt, der oben dokumentiert ist – trag deinen API-Schlüssel einmal in den Einstellungen der Erweiterung ein, und jede Veröffentlichung liefert ab dann sofort einen teilbaren Link. Funktioniert in Chrome am PC (und anderen Chromium-Browsern), Firefox am PC und Firefox für Android.

YourImageShare Capture für Firefox holen YourImageShare Capture für Chrome holen

ShareX

Lade den benutzerdefinierten Uploader unten herunter, geh dann in ShareX zu Destinations > Custom uploader settings > Import > from file, öffne die heruntergeladene .sxcu-Datei und ersetze YOUR_API_KEY im Feld Headers durch deinen echten Schlüssel. Lege sie als Ziel für Bilder/Dateien fest, und Aufnahmen werden automatisch hochgeladen.

YourImageShare.sxcu herunterladen

Flameshot (Linux)

Ein kleines Shell-Skript, das flameshot gui ausführt, die Aufnahme hochlädt und den Link in die Zwischenablage kopiert. Leg es in deiner Desktop-Umgebung auf ein Tastenkürzel, anstelle des Standardkürzels von Flameshot.

yis-flameshot-upload.sh herunterladen

# 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)

Ein PowerShell-Skript für das Ziel Externer Befehl von Greenshot. Kompatibel mit der Windows PowerShell 5.1, die bei Windows dabei ist, du musst nichts extra installieren.

yis-greenshot-upload.ps1 herunterladen

# 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"

Forum-Plugins

Füge neben dem Beitragseditor deines Forums einen echten Button „Bild hochladen“ hinzu. Jedes Plugin lädt über denselben /api-Endpunkt hoch, der oben dokumentiert ist, und fügt BBCode an deiner Cursorposition ein – kein separater Tab, kein manuelles Kopieren und Einfügen.

Forum-Uploads sind standardmäßig private: Das Bild funktioniert im Beitrag, aber YourImageShare legt dafür keine eigene Seite an (keine Kommentare, Reaktionen oder Werbung). Jedes Plugin hat eine Einstellung, um auf unlisted umzustellen, wenn du auch eine Seite für alle mit dem Link möchtest.

phpBB

Eine echte Erweiterung für phpBB 3.2/3.3. Entpacke sie in ext/, aktiviere sie unter Anpassen > Erweiterungen verwalten und ersetze dann YOUR_UPLOAD_ONLY_KEY in der Template-Event-Datei der Erweiterung durch deinen echten Nur-Upload-Schlüssel.

Für phpBB herunterladen

SMF (Simple Machines Forum)

Ein echtes SMF-Paket – installiere es über Admin > Paketverwaltung und ersetze dann YOUR_UPLOAD_ONLY_KEY in Sources/yis_forumupload.php durch deinen echten Nur-Upload-Schlüssel.

Für SMF herunterladen

MyBB

Ein echtes Plugin für MyBB 1.8. Kopiere es nach inc/plugins/, aktiviere es unter Konfiguration > Plugins und ersetze dann YOUR_UPLOAD_ONLY_KEY in der Plugin-Datei durch deinen echten Nur-Upload- Schlüssel.

Für MyBB herunterladen

FluxBB, PunBB & ZetaBoards

Diese haben kein offizielles Plugin-System, daher ist es ein kleines Snippet, das du direkt in dein Template (FluxBB/PunBB) oder in die Admin-Oberfläche (ZetaBoards) einfügst – eine vollständige Anleitung zum Kopieren und Einfügen für jedes:

Anleitung für FluxBB Anleitung für PunBB Anleitung für ZetaBoards

WordPress-Plugin

Lagere deine Mediathek auf YourImageShare aus, statt sie auf der lokalen Festplatte zu halten. Neue Bild-/Video-Uploads laufen automatisch über denselben /api- Endpunkt, der oben dokumentiert ist, die lokale Datei (und jede erzeugte Vorschaugröße) wird gelöscht, sobald der Upload bestätigt ist, und jede WordPress- Anhang-URL – im Block-Editor, bei Beitragsbildern, Galerien und in der REST-API – verweist auf die bei YourImageShare gehostete Datei. Kein Shortcode, keine Änderung im Ablauf.

• Eine bestehende Mediathek im Hintergrund (oder mit wp yis offload --all) komplett auslagern, nicht nur neue Uploads
• Bilder und Videos, die schon in Beiträgen eingebunden sind, funktionieren weiter, nachdem ihre lokalen Dateien entfernt wurden
• Vorschaubilder und srcset nutzen unsere 280px-Vorschau, damit kleine Bildplätze keine Dateien in voller Größe laden
• Dateien bis 200MB, in Teilen gesendet, damit große Videos einen Shared-Hosting-Server nie überlasten
• Jede ausgelagerte Datei lässt sich jederzeit wieder lokal speichern
• Eine Spalte in der Mediathek zeigt, was ausgelagert und was noch lokal ist
• Ausgelagerte Dateien werden als private gespeichert: Sie laden überall dort, wo deine Website sie verwendet, bekommen aber keine eigene Seite auf YourImageShare

Auf WordPress.org holen ZIP herunterladen

In WordPress: Plugins > Installieren, nach YourImageShare Media Offload suchen, dann installieren und aktivieren.

Aus dem Blog