Documentação da API

Como obter uma chave de API

Entre na sua conta, acesse Minha conta e abra a aba API. Sua chave aparece ali, junto com um botão Gerar novamente. Gerar a chave de novo invalida a antiga na hora, então atualize todos os lugares onde ela é usada antes de clicar.

Essa aba também tem uma segunda chave, independente: a chave somente para upload. Veja a dica abaixo e Plugins para fóruns para saber quando usá-la.

Autenticação

Envie sua chave em um cabeçalho (o jeito recomendado, já que query strings costumam ir parar em logs de acesso, logs de proxy e cabeçalhos Referer):

X-API-Key: YOUR_API_KEY

O parâmetro de query ?key= também funciona, mantido por compatibilidade com integrações antigas e comandos curl rápidos e pontuais. Se os dois estiverem presentes, o cabeçalho prevalece.

?key=YOUR_API_KEY

Endpoints

Enviar, listar e excluir usam a mesma autenticação e o mesmo controle de limites; arquivos grandes podem ser enviados antes em partes.

POST /api - Enviar um arquivo

Envia um único arquivo para a conta autenticada.

Tipos aceitos: imagens JPG, PNG, GIF, WEBP, AVIF, BMP, TIFF, HEIC ou HEIF; vídeo MP4, WEBM ou AVI (a lista exata pode crescer com o tempo). HEIC/HEIF e TIFF são armazenados como WebP, vídeos que não sejam MP4/WebM são convertidos para MP4, e imagens JPEG/PNG maiores são convertidas para WebP logo após o upload quando isso as deixa visivelmente menores. Tamanho máximo: 200MB; arquivos grandes demais 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 - Arquivos grandes

Uma única requisição comporta no máximo 100MB. Para arquivos maiores (até 200MB), ou para manter cada requisição pequena em uma conexão lenta, envie o arquivo em partes de no máximo 5MB e finalize com POST /api:

1. Escolha um id de upload: 32 caracteres hexadecimais aleatórios.
2. Para cada parte, faça POST /api/chunk (multipart/form-data) com upload_id, index (começando 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 no lugar de uploads, mais qualquer outro campo de upload. A resposta é a resposta normal de upload.

As partes de um upload não finalizado são excluídas após 2 horas. Só o POST /api final conta para os limites de upload.

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

GET retorna um dos seus uploads com os mesmos campos da lista abaixo. PATCH altera visibility, title ou description (campos de formulário ou JSON; um título ou descrição vazio apaga o valor) e responde com o upload atualizado. Os dois exigem a chave de API completa; retornam 404 se não houver esse upload 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 arquivo

Troca o arquivo de um dos seus uploads e mantém o id, a página e todos os links. Qualquer tipo permitido funciona, até um diferente (uma imagem pode virar um vídeo). Envie o novo arquivo como uploads (ou o upload_id de um arquivo enviado em partes com POST /api/chunk); keep_original funciona como no upload. O novo arquivo passa pelas mesmas verificações e conversões de um upload novo, e a versão anterior é removida. Exige a chave de API completa; retorna 404 se não houver esse upload na sua conta e 409 se ele for protegido por senha ou tiver 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 seus uploads

Retorna uma lista paginada dos uploads da conta autenticada (de qualquer origem: API, site ou editor), dos mais novos para os mais antigos, 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 de upload acima (em um upload protegido por senha, path e thumb são links assinados de curta duração). Ainda não existe um endpoint único para "obter um upload", então esta lista também serve para descobrir o id de um arquivo depois.

DELETE /api/{id} - Excluir um upload

Exclui permanentemente um dos uploads da conta autenticada. Isso não pode ser desfeito pela API. {id} é o valor retornado como id pelos endpoints de upload ou de listagem.

Resposta - 200 OK:

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

404 se não existir upload com esse id na sua conta (ou ele nunca foi seu, ou já foi excluído).

Limites de uso

Cada chave de API tem cotas independentes por minuto e por dia, além de um teto diário por IP, mais amplo, como proteção contra um mesmo IP que alterne entre várias chaves. Uploads, listagens e exclusões compartilham os mesmos limites.

Esses limites podem mudar. Toda resposta inclui os cabeçalhos padrão de limite de uso:

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

Um 429 é retornado quando um limite é excedido, com um cabeçalho Retry-After informando quantos segundos esperar.

Erros

Toda resposta de erro usa o mesmo formato, 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 em erros da API, em vez de exigir o tratamento HTTP bruto.

JavaScript / TypeScript

Sem dependências, funciona no Node.js e em navegadores. Também está no JSR como @yourimageshare/yourimageshare - npx jsr add @yourimageshare/yourimageshare - mesmo código-fonte, 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 própria extensão curl do PHP), PHP 7.4+. Código-fonte no GitHub.

composer require yourimageshare/yourimageshare-php

Go

Sem dependências (somente a biblioteca padrão), Go 1.18+. Veja o 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 trazer um runtime assíncrono, mais serde), Rust 1.70+. Código-fonte no GitHub.

cargo add yourimageshare

Ruby

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

gem install yourimageshare

.NET

Uma dependência (o próprio System.Text.Json da Microsoft), direcionada ao netstandard2.0, então funciona tanto no .NET Framework quanto no .NET moderno. Código-fonte no GitHub. Desenvolvida e verificada com esta API em produção; publicação no NuGet em breve.

dotnet add package YourImageShare

Dart / Flutter

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

dart pub add yourimageshare

Elixir

Uma dependência (Req), Elixir 1.14+. Retorna tuplas {:ok, result}| {:error, reason}, o equivalente direto do tratamento de erros desta API em todos os outros SDKs, além de 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 tela em um relatório de bug, na descrição de um PR ou em uma conversa de suporte como um link de verdade, em vez de um blob base64 ou de uma etapa manual de upload. Funciona do mesmo jeito com o Claude Desktop e qualquer outro cliente MCP. Execute direto com npx, sem etapa de instalação:

npx yourimageshare-mcp

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

Também está no MCP Registry oficial (como io.github.yourimageshare/yourimageshare) e listado no Smithery e no Glama, caso seu cliente MCP instale por um deles.

Novo no MCP? Veja como conectar o Claude e o ChatGPT a esta API via MCP para um passo a passo 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 isso por você; esta versão direta é para quem prefere 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 captura de tela

Uma extensão de navegador, mais configurações e scripts prontos para enviar capturas de tela direto para o YourImageShare, sem upload manual. Cada uma envia pelo mesmo endpoint /api documentado acima.

Extensão de navegador (Chrome & Firefox)

A extensão YourImageShare Capture para Chrome e Firefox dispensa scripts e arquivos de configuração. Ela captura a área visível, uma região selecionada com o mouse ou uma página inteira com rolagem, abre um editor integrado para setas, texto, desfoque/ocultação e outras anotações e então baixa o resultado, copia para a área de transferência ou publica direto no YourImageShare com um clique. A publicação usa o mesmo endpoint /api documentado acima: adicione sua chave de API uma vez nas Configurações da extensão e cada publicação a partir daí retorna um link compartilhável na hora. Funciona no Chrome para computador (e em outros navegadores Chromium), no Firefox para computador e no Firefox para Android.

Baixar o YourImageShare Capture para Firefox Baixar o YourImageShare Capture para Chrome

ShareX

Baixe o uploader personalizado abaixo e, no ShareX, vá em Destinations > Custom uploader settings > Import > from file, abra o .sxcu baixado e substitua YOUR_API_KEY no campo Headers pela sua chave real. Defina-o como destino de imagem/arquivo e as capturas serão enviadas automaticamente.

Baixar YourImageShare.sxcu

Flameshot (Linux)

Um pequeno script de shell que executa flameshot gui, envia a captura e copia o link para a área de transferência. Associe-o a um atalho de teclado no seu ambiente de desktop no lugar do atalho padrão do Flameshot.

Baixar 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 integrado External command do Greenshot. Compatível com o Windows PowerShell 5.1 que acompanha o Windows, sem precisar instalar nada extra.

Baixar 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 botão de "Enviar imagem" de verdade ao lado do editor de posts do seu fórum. Cada um envia pelo mesmo endpoint /api documentado acima e insere BBCode onde está o cursor, sem aba separada e sem copiar e colar manualmente.

Os uploads de fóruns são privados por padrão: a imagem funciona no post, mas o YourImageShare não cria uma página própria para ela (sem comentários, reações nem anúncios). Cada plugin tem uma configuração para mudar para unlisted se você também quiser uma página para quem tiver o link.

phpBB

Uma extensão de verdade para phpBB 3.2/3.3. Descompacte em ext/, ative em Customise > Manage extensions e substitua YOUR_UPLOAD_ONLY_KEY no arquivo de evento de template da extensão pela sua chave real somente para upload.

Baixar para phpBB

SMF (Simple Machines Forum)

Um pacote de verdade para SMF: instale em Admin > Package Manager e substitua YOUR_UPLOAD_ONLY_KEY em Sources/yis_forumupload.php pela sua chave real somente para upload.

Baixar para SMF

MyBB

Um plugin de verdade para MyBB 1.8. Copie para inc/plugins/, ative em Configuration > Plugins e substitua YOUR_UPLOAD_ONLY_KEY no arquivo do plugin pela sua chave real somente para upload.

Baixar para MyBB

FluxBB, PunBB & ZetaBoards

Eles não têm um sistema formal de plugins, então é um pequeno trecho de código colado diretamente no seu template (FluxBB/PunBB) ou no Admin CP (ZetaBoards). Veja as instruções completas de copiar e colar de cada um:

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

Plugin para WordPress

Transfira sua Biblioteca de mídia para o YourImageShare em vez do disco local. Os novos uploads de imagens e vídeos passam automaticamente pelo mesmo endpoint /api documentado acima, o arquivo local (e todos os tamanhos de miniatura gerados) é excluído assim que o upload é confirmado, e toda URL de anexo do WordPress (editor de blocos, imagens destacadas, galerias, API REST) passa a apontar para o arquivo hospedado no YourImageShare. Sem shortcode, sem mudar seu fluxo de trabalho.

• Transfira em massa uma Biblioteca de mídia existente em segundo plano (ou com wp yis offload --all), e não só os uploads novos
• Imagens e vídeos já inseridos em posts continuam funcionando depois que os arquivos locais são removidos
• Miniaturas e srcset usam a nossa miniatura de 280px, então espaços pequenos de imagem não carregam arquivos em tamanho original
• Arquivos de até 200MB, enviados em partes para que vídeos grandes nunca sobrecarreguem uma hospedagem compartilhada
• Restaure qualquer arquivo transferido de volta para o armazenamento local a qualquer momento
• Uma coluna na Biblioteca de mídia mostra o que foi transferido e o que ainda está local
• Os arquivos transferidos são armazenados como privados: carregam onde o seu site os usa, mas não ganham uma página própria no YourImageShare

Obter no WordPress.org Baixar o ZIP

No WordPress: Plugins > Add New, pesquise por YourImageShare Media Offload, depois clique em Install e Activate.

Do blog