Documentação da API

Obter uma chave de API

Inicie sessão, aceda a A minha conta e abra o separador API. A sua chave aparece aí, juntamente com um botão Regenerar. Regenerar uma chave invalida imediatamente a anterior, por isso atualize todos os sítios onde ela é usada antes de clicar.

Esse separador tem também uma segunda chave independente, a chave apenas para carregar - veja a dica abaixo e os Plugins para fóruns para saber quando a usar.

Autenticação

Envie a chave num cabeçalho (é a opção preferida, porque os parâmetros do URL costumam ir parar aos registos de acesso, aos registos de proxies e aos cabeçalhos Referer):

X-API-Key: YOUR_API_KEY

O parâmetro ?key= no URL também funciona, mantido por compatibilidade com integrações antigas e comandos curl pontuais. Se ambos estiverem presentes, o cabeçalho prevalece.

?key=YOUR_API_KEY

Endpoints

Carregar, listar e eliminar partilham a mesma autenticação e os mesmos limites de pedidos; os ficheiros grandes podem ser enviados primeiro em partes.

POST /api - Carregar um ficheiro

Carrega um único ficheiro para a conta autenticada.

Tipos aceites: imagens JPG, PNG, GIF, WEBP, AVIF, BMP, TIFF, HEIC ou HEIF; vídeo MP4, WEBM ou AVI (a lista exata pode ser alargada com o tempo). Os ficheiros HEIC/HEIF e TIFF são guardados como WebP, os vídeos que não sejam MP4/WebM são convertidos para MP4, e as imagens JPEG/PNG maiores são convertidas para WebP pouco depois do carregamento, quando isso as torna sensivelmente mais pequenas. Tamanho máximo: 200MB; os ficheiros demasiado grandes ou ilegíveis são rejeitados com um 422.

Resposta - 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 - Ficheiros grandes

Um único pedido pode transportar no máximo 100MB. Para ficheiros maiores (até 200MB), ou para manter cada pedido pequeno numa ligação lenta, envie o ficheiro em partes de, no máximo, 5MB e termine com POST /api:

1. Escolha um id de carregamento: 32 carateres hexadecimais aleatórios.
2. Para cada parte, faça POST /api/chunk (multipart/form-data) com upload_id, index (começa em 0), total (número de partes) e os bytes em chunk. A resposta é {"type": "success", "chunk_size": 5242880}.
3. Faça POST /api com upload_id e filename em vez de uploads, mais quaisquer outros campos de carregamento. A resposta é a resposta normal de um carregamento.

As partes de um carregamento que não seja concluído são eliminadas após 2 horas. Só o POST /api final conta para os limites de carregamento.

GET /api/{id} e PATCH /api/{id} - Um carregamento

GET devolve um dos seus carregamentos com os mesmos campos da lista abaixo. PATCH altera o seu visibility, title ou description (campos de formulário ou JSON; um título ou descrição vazio apaga-o) e responde com o carregamento atualizado. Ambos precisam da chave de API completa; devolvem 404 se não existir esse carregamento na sua conta.

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 - Substituir o ficheiro

Troca o ficheiro de um dos seus carregamentos e mantém o seu id, a página e todos os links. Qualquer tipo permitido serve, mesmo diferente (uma imagem pode passar a vídeo). Envie o novo ficheiro como uploads (ou o upload_id de um ficheiro enviado em partes com POST /api/chunk); keep_original funciona como no carregamento. O novo ficheiro passa pelas mesmas verificações e conversões de um carregamento novo, e a versão anterior é removida. Precisa da chave de API completa; devolve 404 se não existir esse carregamento na sua conta e 409 se estiver protegido por palavra-passe ou com limite de visualizações.

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

GET /api - Listar os seus carregamentos

Devolve uma lista paginada dos carregamentos da conta autenticada (de qualquer origem: API, site ou editor), do mais recente para o mais antigo, 50 por página.

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

Os campos têm aqui o mesmo significado que na resposta do carregamento acima (num carregamento protegido por palavra-passe, path e thumb são links assinados de curta duração). Ainda não existe um endpoint único para obter um carregamento, por isso esta lista é também a forma de consultar o id de um ficheiro mais tarde.

DELETE /api/{id} - Eliminar um carregamento

Elimina de forma permanente um dos carregamentos da conta autenticada. Não é possível anular através da API. {id} é o valor devolvido como id pelos endpoints de carregamento ou de listagem.

Resposta - 200 OK:

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

404 se não existir nenhum carregamento com esse id na sua conta (ou nunca foi seu, ou já foi eliminado).

Limites de pedidos

Cada chave de API tem quotas independentes por minuto e por dia, além de um limite diário mais amplo por IP, como salvaguarda contra um IP que use várias chaves à vez. Carregamentos, listagens e eliminações partilham os mesmos limites.

Estes limites podem mudar. Todas as respostas incluem os cabeçalhos padrão de limite de pedidos:

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

É devolvido um 429 quando um limite é excedido, com um cabeçalho Retry-After que indica quantos segundos deve esperar.

Erros

Todas as respostas de erro têm a mesma estrutura, independentemente do endpoint ou da causa:

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

Bibliotecas cliente

SDKs oficiais que encapsulam os endpoints acima com resultados tipados e lançam exceções nos erros da API, em vez de tratar HTTP em bruto.

JavaScript / TypeScript

Sem dependências, funciona em Node.js e em navegadores. Também no JSR como @yourimageshare/yourimageshare - npx jsr add @yourimageshare/yourimageshare - mesmo código, publicado diretamente em TypeScript.

npm install yourimageshare

Python

Uma dependência (requests), Python 3.8+.

pip install yourimageshare

PHP

Sem dependências do Composer (usa a extensão curl do próprio PHP), PHP 7.4+. Código-fonte no GitHub.

composer require yourimageshare/yourimageshare-php

Go

Sem dependências (só a biblioteca padrão), Go 1.18+. Consulte pkg.go.dev para a documentação de referência completa.

go get github.com/yourimageshare/yourimageshare/go

Rust

Duas dependências (ureq para HTTP bloqueante, sem arrastar um runtime assíncrono, e serde), Rust 1.70+. Código-fonte no GitHub.

cargo add yourimageshare

Ruby

Sem dependências de gems (Net::HTTP da biblioteca padrão + json), Ruby 2.7+. Código-fonte no GitHub.

gem install yourimageshare

.NET

Uma dependência (o System.Text.Json da própria Microsoft), destinado a netstandard2.0, por isso funciona tanto no .NET Framework como no .NET moderno. Código-fonte no GitHub. Desenvolvido e verificado com esta API real; publicação no NuGet em breve.

dotnet add package YourImageShare

Dart / Flutter

Uma dependência (http, o pacote da própria equipa do Dart), Dart 2.17+. Código-fonte no GitHub. Desenvolvido e verificado com esta API real; publicação no pub.dev em breve.

dart pub add yourimageshare

Elixir

Uma dependência (Req), Elixir 1.14+. Devolve tuplos {:ok, result}| {:error, reason}, o equivalente direto do tratamento de erros desta API em todos os outros SDKs, e também variantes com ponto de exclamação que lançam exceções. Código-fonte no GitHub, documentação no HexDocs.

{:yourimageshare, "~> 1.1"}

Servidor MCP

Para agentes de programação com IA (Claude Code, Cursor e outras ferramentas compatíveis com MCP) - cole uma captura de ecrã num relatório de erro, na descrição de um PR ou num pedido de suporte como um link real, em vez de um blob base64 ou de um passo manual de carregamento. Funciona da mesma forma com o Claude Desktop e qualquer outro cliente MCP. Execute diretamente com npx, sem instalação:

npx yourimageshare-mcp

Ferramentas: upload_image (um ficheiro local, conteúdo inline ou um link, até 200MB, com visibilidade, título e eliminação automática opcionais), list_uploads, get_upload, update_upload e delete_upload.

Também no Registo MCP oficial (como io.github.yourimageshare/yourimageshare) e listado no Smithery e no Glama, se o seu cliente MCP instalar a partir de um desses.

Novo no MCP? Veja como ligar o Claude e o ChatGPT a esta API através de MCP para um guia completo de configuração.

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

O SDK oficial de Go acima já faz isto por si; esta versão em bruto serve para quem preferir não adicionar a dependência.

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
}

Ferramentas de capturas de ecrã

Uma extensão de navegador, mais configurações e scripts prontos para enviar capturas de ecrã diretamente para o YourImageShare, sem carregamento manual. Todos carregam através do mesmo endpoint /api documentado acima.

Extensão de navegador (Chrome & Firefox)

A extensão YourImageShare Capture para Chrome e Firefox dispensa scripts e ficheiros de configuração. Captura a área visível, uma região selecionada com o rato ou uma página completa com deslocamento, abre um editor integrado para setas, texto, desfoque/ocultação e outras anotações e depois descarrega o resultado, copia-o para a área de transferência ou publica-o diretamente no YourImageShare com um clique. A publicação usa o mesmo endpoint /api documentado acima: adicione a sua chave de API uma vez nas Definições da extensão e cada publicação a partir daí devolve imediatamente um link para partilhar. Funciona no Chrome para computador (e noutros navegadores Chromium), no Firefox para computador e no Firefox para Android.

Obter o YourImageShare Capture para Firefox Obter o YourImageShare Capture para Chrome

ShareX

Descarregue o carregador personalizado abaixo e, no ShareX, aceda a Destinations > Custom uploader settings > Import > from file, abra o ficheiro .sxcu descarregado e substitua YOUR_API_KEY no campo Headers pela sua chave real. Defina-o como destino de imagens/ficheiros e as capturas são carregadas automaticamente.

Descarregar YourImageShare.sxcu

Flameshot (Linux)

Um pequeno script de shell que executa flameshot gui, carrega a captura e copia o link para a área de transferência. Associe-o a um atalho de teclado no seu ambiente de trabalho, em vez do atalho predefinido do Flameshot.

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

Um script PowerShell para o destino External command integrado do Greenshot. Compatível com o Windows PowerShell 5.1 que vem com o Windows, sem instalar mais nada.

Descarregar 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 fóruns

Adicione um verdadeiro botão "Carregar imagem" junto ao editor de mensagens do seu fórum. Todos carregam através do mesmo endpoint /api documentado acima e inserem BBCode na posição do cursor, sem separador extra nem copiar e colar manualmente.

Os carregamentos de fóruns são privados por predefinição: a imagem funciona na mensagem, mas o YourImageShare não lhe dá página própria (sem comentários, reações nem anúncios). Cada plugin tem uma definição para passar a unlisted, se quiser também uma página para quem tiver o link.

phpBB

Uma extensão phpBB 3.2/3.3 a sério. Descompacte em ext/, ative-a em Personalizar > Gerir extensões e depois substitua YOUR_UPLOAD_ONLY_KEY no ficheiro de eventos de modelo da extensão pela sua chave real apenas para carregar.

Descarregar para phpBB

SMF (Simple Machines Forum)

Um pacote SMF a sério: instale-o em Admin > Package Manager e depois substitua YOUR_UPLOAD_ONLY_KEY em Sources/yis_forumupload.php pela sua chave real apenas para carregar.

Descarregar para SMF

MyBB

Um plugin MyBB 1.8 a sério. Copie para inc/plugins/, ative-o em Configuration > Plugins e depois substitua YOUR_UPLOAD_ONLY_KEY no ficheiro do plugin pela sua chave real apenas para carregar.

Descarregar para MyBB

FluxBB, PunBB & ZetaBoards

Não têm um sistema formal de plugins, por isso é um pequeno excerto colado diretamente no modelo (FluxBB/PunBB) ou no Painel de Administração (ZetaBoards), com instruções completas de copiar e colar para cada um:

Instruções do FluxBB Instruções do PunBB Instruções do ZetaBoards

Plugin de WordPress

Transfira a sua Biblioteca de multimédia para o YourImageShare em vez de a manter no disco local. Os novos carregamentos de imagens/vídeos passam automaticamente pelo mesmo endpoint /api documentado acima, o ficheiro local (e todos os tamanhos de miniatura gerados) é eliminado assim que o carregamento é confirmado, e todos os URL de anexos do WordPress (o editor de blocos, imagens de destaque, galerias, API REST) passam a apontar para o ficheiro alojado no YourImageShare. Sem shortcode, sem mudar a sua forma de trabalhar.

• Transfira em massa uma Biblioteca de multimédia existente em segundo plano (ou com wp yis offload --all), e não apenas os novos carregamentos
• As imagens e os vídeos já colocados em artigos continuam a funcionar depois de os ficheiros locais serem removidos
• As miniaturas e o srcset usam a nossa miniatura de 280px, para que os espaços pequenos não carreguem ficheiros em tamanho real
• Ficheiros até 200MB, enviados em partes para que vídeos grandes nunca sobrecarreguem um alojamento partilhado
• Restaure qualquer ficheiro transferido para o armazenamento local em qualquer altura
• Uma coluna na Biblioteca de multimédia mostra o que foi transferido e o que ainda é local
• Os ficheiros transferidos são guardados como privados: carregam onde quer que o seu site os use, mas não têm página própria no YourImageShare

Obter em WordPress.org Descarregar o ZIP

No WordPress: Plugins > Adicionar novo, procure YourImageShare Media Offload e depois Instalar e Ativar.

Do blogue