Documentation de l'API

Obtenir une clé d'API

Connectez-vous, allez dans Mon compte et ouvrez l'onglet API. Votre clé y est affichée, avec un bouton Régénérer. Régénérer une clé invalide immédiatement l'ancienne : mettez donc à jour tous les endroits où elle est utilisée avant de cliquer.

Cet onglet propose aussi une seconde clé indépendante, la clé réservée à la mise en ligne : consultez l'astuce ci-dessous et la section Extensions pour forums pour savoir quand l'utiliser à la place.

Authentification

Envoyez votre clé dans un en-tête (méthode recommandée, car les chaînes de requête finissent souvent dans les journaux d'accès, les journaux de proxy et les en-têtes Referer) :

X-API-Key: YOUR_API_KEY

Un paramètre de requête ?key= fonctionne aussi, conservé pour la compatibilité avec d'anciennes intégrations et pour des commandes curl ponctuelles. Si les deux sont présents, l'en-tête l'emporte.

?key=YOUR_API_KEY

Endpoints

La mise en ligne, la liste et la suppression partagent la même authentification et la même limitation de débit ; les fichiers volumineux peuvent d'abord être envoyés par morceaux.

POST /api - Mettre en ligne un fichier

Met en ligne un seul fichier pour le compte authentifié.

Types acceptés : images JPG, PNG, GIF, WEBP, AVIF, BMP, TIFF, HEIC ou HEIF ; vidéos MP4, WEBM ou AVI (la liste exacte peut s'étendre avec le temps). Les fichiers HEIC/HEIF et TIFF sont stockés en WebP, les vidéos autres que MP4/WebM sont converties en MP4, et les images JPEG/PNG plus volumineuses sont converties en WebP peu après leur mise en ligne lorsque cela les rend sensiblement plus légères. Taille max. : 200 Mo ; les fichiers trop volumineux ou illisibles sont rejetés avec une erreur 422.

Réponse - 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 - Fichiers volumineux

Une seule requête peut contenir 100 Mo au maximum. Pour des fichiers plus gros (jusqu'à 200 Mo), ou pour garder chaque requête légère sur une connexion lente, envoyez le fichier par morceaux de 5 Mo maximum, puis terminez avec POST /api :

1. Choisissez un identifiant de mise en ligne : 32 caractères hexadécimaux aléatoires.
2. Pour chaque morceau, faites un POST /api/chunk (multipart/form-data) avec upload_id, index (à partir de 0), total (nombre de morceaux) et les octets dans chunk. La réponse est {"type": "success", "chunk_size": 5242880}.
3. Faites un POST /api avec upload_id et filename à la place de uploads, plus tout autre champ de mise en ligne. La réponse est la réponse normale de mise en ligne.

Les morceaux d'un fichier dont la mise en ligne n'est pas terminée sont supprimés au bout de 2 heures. Seul le POST /api final compte dans les limites de mise en ligne.

GET /api/{id} et PATCH /api/{id} - Un fichier

GET renvoie l'un de vos fichiers avec les mêmes champs que la liste ci-dessous. PATCH modifie sa visibility, son title ou sa description (champs de formulaire ou JSON ; un titre ou une description vide l'efface) et renvoie le fichier mis à jour. Les deux nécessitent la clé d'API complète ; 404 s'il n'existe aucun fichier de ce type sur votre compte.

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 - Remplacer le fichier

Remplace le fichier associé à l'un de vos fichiers en ligne et conserve son identifiant, sa page et tous ses liens. Tout type autorisé fonctionne, même différent (une image peut devenir une vidéo). Envoyez le nouveau fichier dans uploads (ou le upload_id d'un fichier envoyé par morceaux avec POST /api/chunk) ; keep_original fonctionne comme pour la mise en ligne. Le nouveau fichier subit les mêmes contrôles et conversions qu'un nouveau fichier, et la version précédente est supprimée. Nécessite la clé d'API complète ; 404 s'il n'existe aucun fichier de ce type sur votre compte, 409 s'il est protégé par mot de passe ou limité en nombre de vues.

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

GET /api - Lister vos fichiers

Renvoie une liste paginée des fichiers du compte authentifié (quelle que soit la source : API, site web ou éditeur), du plus récent au plus ancien, 50 par page.

Réponse - 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 }
}

Les champs ont ici le même sens que dans la réponse de mise en ligne ci-dessus (pour un fichier protégé par mot de passe, path et thumb sont des liens signés de courte durée). Il n'existe pas encore d'endpoint unique pour « récupérer un fichier » : cette liste permet donc aussi de retrouver l'id d'un fichier après coup.

DELETE /api/{id} - Supprimer un fichier

Supprime définitivement l'un des fichiers du compte authentifié. Cette action ne peut pas être annulée depuis l'API. {id} est la valeur renvoyée dans id par les endpoints de mise en ligne ou de liste.

Réponse - 200 OK :

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

404 si aucun fichier avec cet identifiant n'existe sur votre compte (soit il ne vous a jamais appartenu, soit il a déjà été supprimé).

Limites de débit

Chaque clé d'API a des quotas indépendants par minute et par jour, ainsi qu'un plafond quotidien plus large par adresse IP, qui sert de garde-fou contre une même IP utilisant plusieurs clés à tour de rôle. Les mises en ligne, les listes et les suppressions partagent les mêmes limites.

Ces limites peuvent évoluer. Chaque réponse inclut des en-têtes de limitation de débit standard :

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

Une erreur 429 est renvoyée dès qu'une limite est dépassée, avec un en-tête Retry-After qui indique le nombre de secondes à attendre.

Erreurs

Toutes les réponses d'erreur ont la même structure, quels que soient l'endpoint ou la cause :

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

Bibliothèques clientes

SDK officiels qui encapsulent les endpoints ci-dessus avec des résultats typés et lèvent une exception en cas d'erreur d'API, au lieu d'une gestion HTTP brute.

JavaScript / TypeScript

Aucune dépendance, fonctionne dans Node.js et dans les navigateurs. Également sur JSR sous le nom @yourimageshare/yourimageshare - npx jsr add @yourimageshare/yourimageshare - même code source, publié directement en TypeScript.

npm install yourimageshare

Python

Une seule dépendance (requests), Python 3.8+.

pip install yourimageshare

PHP

Aucune dépendance Composer (utilise l'extension curl native de PHP), PHP 7.4+. Code source sur GitHub.

composer require yourimageshare/yourimageshare-php

Go

Aucune dépendance (bibliothèque standard uniquement), Go 1.18+. Consultez pkg.go.dev pour la documentation de référence complète.

go get github.com/yourimageshare/yourimageshare/go

Rust

Deux dépendances (ureq pour du HTTP bloquant, sans runtime asynchrone, plus serde), Rust 1.70+. Code source sur GitHub.

cargo add yourimageshare

Ruby

Aucune dépendance gem (Net::HTTP de la bibliothèque standard + json), Ruby 2.7+. Code source sur GitHub.

gem install yourimageshare

.NET

Une seule dépendance (System.Text.Json de Microsoft), cible netstandard2.0 et fonctionne donc avec .NET Framework comme avec le .NET moderne. Code source sur GitHub. Développé et vérifié avec cette API en production ; publication sur NuGet prochainement.

dotnet add package YourImageShare

Dart / Flutter

Une seule dépendance (http, le paquet officiel de l'équipe Dart), Dart 2.17+. Code source sur GitHub. Développé et vérifié avec cette API en production ; publication sur pub.dev prochainement.

dart pub add yourimageshare

Elixir

Une seule dépendance (Req), Elixir 1.14+. Renvoie des tuples {:ok, result}| {:error, reason}, l'équivalent direct de la gestion des erreurs de cette API dans tous les autres SDK, ainsi que des variantes avec point d'exclamation qui lèvent une exception. Code source sur GitHub, documentation sur HexDocs.

{:yourimageshare, "~> 1.1"}

Serveur MCP

Pour les agents de programmation IA (Claude Code, Cursor et autres outils compatibles MCP) : collez une capture d'écran dans un rapport de bug, une description de PR ou un échange de support sous forme de vrai lien, au lieu d'un blob base64 ou d'une étape de mise en ligne manuelle. Fonctionne de la même façon avec Claude Desktop et tout autre client MCP. Lancez-le directement avec npx, sans étape d'installation :

npx yourimageshare-mcp

Outils : upload_image (un fichier local, un contenu en ligne ou un lien, jusqu'à 200 Mo, avec visibilité, titre et suppression automatique en option), list_uploads, get_upload, update_upload et delete_upload.

Également dans le registre MCP officiel (sous le nom io.github.yourimageshare/yourimageshare) et référencé sur Smithery et Glama, si votre client MCP s'installe depuis l'un de ces services.

Vous découvrez MCP ? Consultez comment connecter Claude et ChatGPT à cette API via MCP pour un guide d'installation complet.

Exemples de code

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)

Le SDK Go officiel ci-dessus s'en charge pour vous : cette version brute est destinée à ceux qui préfèrent ne pas ajouter la dépendance.

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
}

Outils de capture d'écran

Une extension de navigateur ainsi que des configurations et scripts prêts à l'emploi pour envoyer vos captures d'écran directement sur YourImageShare, sans mise en ligne manuelle. Chacun passe par le même endpoint /api documenté ci-dessus.

Extension de navigateur (Chrome & Firefox)

L'extension YourImageShare Capture pour Chrome et Firefox se passe totalement de scripts et de fichiers de configuration. Elle capture la zone visible, une région sélectionnée à la souris ou une page entière avec défilement, ouvre un éditeur intégré pour ajouter des flèches, du texte, du flou/masquage et d'autres annotations, puis télécharge le résultat, le copie dans votre presse-papiers ou le publie directement sur YourImageShare en un clic. La publication utilise le même endpoint /api documenté ci-dessus : ajoutez votre clé d'API une seule fois dans les paramètres de l'extension, et chaque publication renvoie ensuite immédiatement un lien partageable. Fonctionne sur Chrome pour ordinateur (et les autres navigateurs Chromium), Firefox pour ordinateur et Firefox pour Android.

Obtenir YourImageShare Capture pour Firefox Obtenir YourImageShare Capture pour Chrome

ShareX

Téléchargez la configuration d'envoi personnalisée ci-dessous, puis dans ShareX allez dans Destinations > Paramètres de l'uploader personnalisé > Importer > depuis un fichier, ouvrez le fichier .sxcu téléchargé et remplacez YOUR_API_KEY dans le champ Headers par votre vraie clé. Définissez-le comme destination d'images/fichiers et vos captures seront mises en ligne automatiquement.

Télécharger YourImageShare.sxcu

Flameshot (Linux)

Un petit script shell qui lance flameshot gui, met en ligne la capture et copie le lien dans votre presse-papiers. Associez-le à un raccourci clavier dans votre environnement de bureau à la place de celui par défaut de Flameshot.

Télécharger 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)

Un script PowerShell pour la destination Commande externe intégrée à Greenshot. Compatible avec Windows PowerShell 5.1, fourni avec Windows, sans installation supplémentaire.

Télécharger 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"

Extensions pour forums

Ajoutez un vrai bouton « Mettre en ligne une image » à côté de l'éditeur de messages de votre forum. Chacune passe par le même endpoint /api documenté ci-dessus et insère du BBCode à l'emplacement du curseur : pas d'onglet séparé, pas de copier-coller manuel.

Les fichiers mis en ligne depuis un forum sont privés par défaut : l'image fonctionne dans le message, mais YourImageShare ne lui crée pas de page dédiée (pas de commentaires, de réactions ni de publicités). Chaque extension propose un réglage pour passer en unlisted si vous souhaitez aussi une page pour toute personne disposant du lien.

phpBB

Une vraie extension phpBB 3.2/3.3. Décompressez-la dans ext/, activez-la dans Personnaliser > Gérer les extensions, puis remplacez YOUR_UPLOAD_ONLY_KEY dans le fichier d'événement de modèle de l'extension par votre vraie clé réservée à la mise en ligne.

Télécharger pour phpBB

SMF (Simple Machines Forum)

Un vrai paquet SMF : installez-le via Admin > Gestionnaire de paquets, puis remplacez YOUR_UPLOAD_ONLY_KEY dans Sources/yis_forumupload.php par votre vraie clé réservée à la mise en ligne.

Télécharger pour SMF

MyBB

Une vraie extension MyBB 1.8. Copiez-la dans inc/plugins/, activez-la dans Configuration > Plugins, puis remplacez YOUR_UPLOAD_ONLY_KEY dans le fichier de l'extension par votre vraie clé réservée à la mise en ligne.

Télécharger pour MyBB

FluxBB, PunBB & ZetaBoards

Ces forums n'ont pas de système d'extensions officiel : il s'agit donc d'un petit extrait de code à coller directement dans votre modèle (FluxBB/PunBB) ou dans le panneau d'administration (ZetaBoards). Instructions complètes de copier-coller pour chacun :

Instructions FluxBB Instructions PunBB Instructions ZetaBoards

Extension WordPress

Déportez votre médiathèque vers YourImageShare au lieu du disque local. Les nouvelles images/vidéos passent automatiquement par le même endpoint /api documenté ci-dessus, le fichier local (et chaque taille de miniature générée) est supprimé une fois la mise en ligne confirmée, et chaque URL de pièce jointe WordPress (éditeur de blocs, images mises en avant, galeries, API REST) pointe vers le fichier hébergé par YourImageShare. Pas de shortcode, aucun changement dans votre façon de travailler.

• Déportez en masse une médiathèque existante en arrière-plan (ou avec wp yis offload --all), pas seulement les nouveaux fichiers
• Les images et vidéos déjà insérées dans des articles continuent de fonctionner après la suppression de leurs fichiers locaux
• Les miniatures et le srcset utilisent notre miniature de 280 px, afin que les petits emplacements d'image ne chargent pas de fichiers en taille réelle
• Fichiers jusqu'à 200 Mo, envoyés par morceaux pour que les grosses vidéos ne surchargent jamais un hébergement mutualisé
• Rapatriez à tout moment n'importe quel fichier déporté vers le stockage local
• Une colonne de la médiathèque indique ce qui est déporté et ce qui est encore local
• Les fichiers déportés sont stockés en privé : ils s'affichent partout où votre site les utilise, mais n'ont pas de page dédiée sur YourImageShare

Obtenir sur WordPress.org Télécharger le ZIP

Dans WordPress : Extensions > Ajouter, recherchez YourImageShare Media Offload, puis Installer et Activer.

Sur le blog