Documentación de la API

Obtener una clave de API

Inicia sesión, ve a Mi cuenta y abre la pestaña API. Allí verás tu clave, junto con un botón Regenerar. Al regenerar una clave, la anterior deja de funcionar de inmediato, así que actualízala en todos los sitios donde la uses antes de pulsarlo.

Esa pestaña también incluye una segunda clave solo para subir, independiente. Consulta el consejo de abajo y Plugins para foros para saber cuándo usarla.

Autenticación

Envía tu clave como encabezado (es lo recomendable, ya que las cadenas de consulta suelen acabar en los registros de acceso, los registros de proxy y los encabezados Referer):

X-API-Key: YOUR_API_KEY

También funciona el parámetro de consulta ?key=, que se mantiene por compatibilidad con integraciones antiguas y para comandos curl rápidos de un solo uso. Si están presentes ambos, gana el encabezado.

?key=YOUR_API_KEY

Endpoints

Subir, listar y eliminar comparten la misma autenticación y los mismos límites de uso; los archivos grandes se pueden enviar antes por partes.

POST /api - Subir un archivo

Sube un único archivo para la cuenta autenticada.

Tipos aceptados: imágenes JPG, PNG, GIF, WEBP, AVIF, BMP, TIFF, HEIC o HEIF; video MP4, WEBM o AVI (la lista exacta puede ampliarse con el tiempo). HEIC/HEIF y TIFF se guardan como WebP, el video que no sea MP4/WebM se convierte a MP4, y las imágenes JPEG/PNG más grandes se convierten a WebP poco después de subirlas cuando eso las hace notablemente más pequeñas. Tamaño máximo: 200MB; los archivos demasiado grandes o ilegibles se rechazan con un 422.

Respuesta - 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 - Archivos grandes

Una sola solicitud puede llevar como máximo 100MB. Para archivos más grandes (hasta 200MB), o para mantener pequeña cada solicitud en una conexión lenta, envía el archivo en partes de como máximo 5MB y termina con POST /api:

1. Elige un id de subida: 32 caracteres hexadecimales aleatorios.
2. Para cada parte, haz POST /api/chunk (multipart/form-data) con upload_id, index (empieza en 0), total (número de partes) y los bytes en chunk. La respuesta es {"type": "success", "chunk_size": 5242880}.
3. Haz POST /api con upload_id y filename en lugar de uploads, además de cualquier otro campo de subida. La respuesta es la respuesta de subida normal.

Las partes de una subida que no se termina se eliminan después de 2 horas. Solo el POST /api final cuenta para los límites de subida.

GET /api/{id} y PATCH /api/{id} - Una subida

GET devuelve una de tus subidas con los mismos campos que la lista de abajo. PATCH cambia su visibility, title o description (campos de formulario o JSON; un título o una descripción vacíos la borran) y responde con la subida actualizada. Ambos requieren la clave de API completa; 404 si no existe esa subida en tu cuenta.

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 - Reemplazar el archivo

Cambia el archivo de una de tus subidas y conserva su id, su página y todos sus enlaces. Sirve cualquier tipo permitido, incluso uno distinto (una imagen puede convertirse en video). Envía el archivo nuevo como uploads (o el upload_id de un archivo enviado por partes con POST /api/chunk); keep_original funciona igual que al subir. El archivo nuevo pasa por las mismas comprobaciones y conversiones que una subida nueva, y la versión anterior se elimina. Requiere la clave de API completa; 404 si no existe esa subida en tu cuenta, 409 si está protegida con contraseña o tiene un límite de visualizaciones.

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

GET /api - Listar tus subidas

Devuelve una lista paginada de las subidas de la cuenta autenticada (de cualquier origen: API, sitio web o editor), de la más reciente a la más antigua, 50 por página.

Respuesta - 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 }
}

Los campos significan aquí lo mismo que en la respuesta de subida de arriba (en una subida protegida con contraseña, path y thumb son enlaces firmados de corta duración). Todavía no existe un endpoint único para "obtener una subida", así que esta lista también sirve para buscar el id de un archivo a posteriori.

DELETE /api/{id} - Eliminar una subida

Elimina de forma permanente una de las subidas de la cuenta autenticada. Esto no se puede deshacer desde la API. {id} es el valor devuelto como id por los endpoints de subida o de lista.

Respuesta - 200 OK:

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

404 si no existe ninguna subida con ese id en tu cuenta (o nunca fue tuya, o ya se eliminó).

Límites de uso

Cada clave de API tiene cuotas independientes por minuto y por día, además de un tope diario por IP más amplio como respaldo frente a una IP que vaya rotando entre varias claves. Las subidas, las listas y las eliminaciones comparten los mismos límites.

Estos límites pueden cambiar. Cada respuesta incluye los encabezados estándar de límite de uso:

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

Se devuelve un 429 cuando se supera un límite, con un encabezado Retry-After que indica cuántos segundos debes esperar.

Errores

Todas las respuestas de error usan la misma estructura, sea cual sea el endpoint o la causa:

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

Bibliotecas cliente

SDK oficiales que envuelven los endpoints anteriores con resultados tipados y lanzan excepciones ante errores de la API, en lugar de tener que gestionar HTTP directamente.

JavaScript / TypeScript

Sin dependencias, funciona en Node.js y en navegadores. También está en JSR como @yourimageshare/yourimageshare - npx jsr add @yourimageshare/yourimageshare - con el mismo código fuente, publicado directamente como TypeScript.

npm install yourimageshare

Python

Una dependencia (requests), Python 3.8+.

pip install yourimageshare

PHP

Sin dependencias de Composer (usa la propia extensión curl de PHP), PHP 7.4+. Código fuente en GitHub.

composer require yourimageshare/yourimageshare-php

Go

Sin dependencias (solo biblioteca estándar), Go 1.18+. Consulta pkg.go.dev para ver la documentación de referencia completa.

go get github.com/yourimageshare/yourimageshare/go

Rust

Dos dependencias (ureq para HTTP bloqueante, sin traer un runtime asíncrono, y serde), Rust 1.70+. Código fuente en GitHub.

cargo add yourimageshare

Ruby

Sin dependencias de gems (Net::HTTP de la biblioteca estándar + json), Ruby 2.7+. Código fuente en GitHub.

gem install yourimageshare

.NET

Una dependencia (el propio System.Text.Json de Microsoft), apunta a netstandard2.0 para que funcione tanto con .NET Framework como con el .NET moderno. Código fuente en GitHub. Creado y verificado con esta API real; se publicará en NuGet en breve.

dotnet add package YourImageShare

Dart / Flutter

Una dependencia (http, el paquete del propio equipo de Dart), Dart 2.17+. Código fuente en GitHub. Creado y verificado con esta API real; se publicará en pub.dev en breve.

dart pub add yourimageshare

Elixir

Una dependencia (Req), Elixir 1.14+. Devuelve tuplas etiquetadas {:ok, result}| {:error, reason}, el equivalente directo del manejo de errores de esta API en todos los demás SDK, además de variantes con exclamación que lanzan excepciones. Código fuente en GitHub, documentación en HexDocs.

{:yourimageshare, "~> 1.1"}

Servidor MCP

Para agentes de programación con IA (Claude Code, Cursor y otras herramientas compatibles con MCP): pega una captura de pantalla en un reporte de error, en la descripción de un PR o en un hilo de soporte como un enlace real, en lugar de un blob en base64 o un paso de subida manual. Funciona igual con Claude Desktop y cualquier otro cliente MCP. Se ejecuta directamente con npx, sin paso de instalación:

npx yourimageshare-mcp

Herramientas: upload_image (un archivo local, contenido en línea o un enlace, hasta 200MB, con visibilidad, título y eliminación automática opcionales), list_uploads, get_upload, update_upload y delete_upload.

También está en el registro oficial de MCP (como io.github.yourimageshare/yourimageshare) y aparece en Smithery y Glama, por si tu cliente MCP se instala desde alguno de ellos.

¿Nuevo en MCP? Consulta cómo conectar Claude y ChatGPT a esta API mediante MCP para ver una guía completa de configuración.

Ejemplos de código

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)

El SDK oficial de Go de arriba se encarga de esto por ti; esta versión directa está aquí para quien prefiera no añadir la dependencia.

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
}

Herramientas de captura de pantalla

Una extensión de navegador, además de configuraciones y scripts listos para enviar capturas de pantalla directamente a YourImageShare, sin subirlas manualmente. Cada una sube a través del mismo endpoint /api documentado arriba.

Extensión de navegador (Chrome y Firefox)

La extensión YourImageShare Capture para Chrome y Firefox prescinde por completo de scripts y archivos de configuración. Captura el área visible, una región seleccionada con el ratón o una página completa con desplazamiento, abre un editor integrado para flechas, texto, desenfoque/tachado y otras anotaciones, y luego descarga el resultado, lo copia al portapapeles o lo publica directamente en YourImageShare con un clic. La publicación usa el mismo endpoint /api documentado arriba: añade tu clave de API una vez en los Ajustes de la extensión y cada publicación a partir de entonces devuelve un enlace para compartir al instante. Funciona en Chrome de escritorio (y otros navegadores Chromium), Firefox de escritorio y Firefox para Android.

Obtener YourImageShare Capture para Firefox Obtener YourImageShare Capture para Chrome

ShareX

Descarga el subidor personalizado de abajo y, en ShareX, ve a Destinos > Configuración de subidor personalizado > Importar > desde archivo, abre el archivo .sxcu descargado y reemplaza YOUR_API_KEY en el campo Encabezados por tu clave real. Configúralo como destino de imágenes/archivos y las capturas se subirán automáticamente.

Descargar YourImageShare.sxcu

Flameshot (Linux)

Un pequeño script de shell que ejecuta flameshot gui, sube la captura y copia el enlace al portapapeles. Asígnalo a un atajo de teclado en tu entorno de escritorio en lugar del predeterminado de Flameshot.

Descargar 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 de PowerShell para el destino integrado Comando externo de Greenshot. Compatible con el Windows PowerShell 5.1 que viene con Windows, sin instalar nada más.

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

Plugins para foros

Añade un verdadero botón "Subir imagen" junto al editor de mensajes de tu foro. Cada uno sube a través del mismo endpoint /api documentado arriba e inserta BBCode en la posición del cursor: sin pestaña aparte y sin copiar y pegar manualmente.

Las subidas desde foros son private por defecto: la imagen funciona en el mensaje, pero YourImageShare no le da una página propia (sin comentarios, reacciones ni anuncios). Cada plugin tiene un ajuste para cambiar a unlisted si también quieres una página para cualquiera que tenga el enlace.

phpBB

Una extensión real de phpBB 3.2/3.3. Descomprímela en ext/, actívala en Personalizar > Gestionar extensiones y reemplaza YOUR_UPLOAD_ONLY_KEY en el archivo de eventos de plantilla de la extensión por tu clave real solo para subir.

Descargar para phpBB

SMF (Simple Machines Forum)

Un paquete real de SMF: instálalo desde Admin > Gestor de paquetes y reemplaza YOUR_UPLOAD_ONLY_KEY en Sources/yis_forumupload.php por tu clave real solo para subir.

Descargar para SMF

MyBB

Un plugin real de MyBB 1.8. Cópialo en inc/plugins/, actívalo en Configuración > Plugins y reemplaza YOUR_UPLOAD_ONLY_KEY en el archivo del plugin por tu clave real solo para subir.

Descargar para MyBB

FluxBB, PunBB y ZetaBoards

Estos no tienen un sistema formal de plugins, así que se trata de un pequeño fragmento que se pega directamente en tu plantilla (FluxBB/PunBB) o en el Panel de administración (ZetaBoards). Instrucciones completas para copiar y pegar de cada uno:

Instrucciones de FluxBB Instrucciones de PunBB Instrucciones de ZetaBoards

Plugin de WordPress

Traslada tu biblioteca de medios a YourImageShare en lugar de al disco local. Las subidas nuevas de imágenes/videos pasan automáticamente por el mismo endpoint /api documentado arriba, el archivo local (y cada tamaño de miniatura generado) se elimina cuando se confirma la subida, y cada URL de adjunto de WordPress (el editor de bloques, las imágenes destacadas, las galerías, la API REST) se resuelve en el archivo alojado en YourImageShare. Sin shortcode y sin cambiar tu forma de trabajar.

• Traslada en bloque una biblioteca de medios existente en segundo plano (o con wp yis offload --all), no solo las subidas nuevas
• Las imágenes y los videos ya incluidos en entradas siguen funcionando después de eliminar sus archivos locales
• Las miniaturas y el srcset usan nuestra miniatura de 280px, así que los espacios pequeños no cargan archivos de tamaño completo
• Archivos de hasta 200MB, enviados por partes para que los videos grandes nunca sobrecarguen un hosting compartido
• Restaura cualquier archivo trasladado al almacenamiento local en cualquier momento
• Una columna en la biblioteca de medios muestra qué está trasladado y qué sigue siendo local
• Los archivos trasladados se guardan como private: se cargan donde tu sitio los use, pero no tienen página propia en YourImageShare

Obtenerlo en WordPress.org Descargar el ZIP

En WordPress: Plugins > Añadir nuevo, busca YourImageShare Media Offload y luego Instalar y Activar.

Del blog