API do imgpile

Envie, compartilhe e gerencie imagens e vídeos de forma programática.

https://imgpile.com/api/v1 — todos os endpoints

https://cdn.imgpile.com/api/v1/media — apenas uploads de arquivo (veja abaixo)

Obtenha um token de API

Entrar ou cadastrar para gerar um token de API.

Conceitos

O imgpile tem dois objetos principais. Entender a diferença vai te poupar tempo.

Mídia

Um único arquivo (imagem ou vídeo). Tem uma URL direta da CDN — ideal para hotlinking, embed ou compartilhamento.

Post

Uma página compartilhável contendo um ou mais itens de mídia. Tem título, descrição, votação, comentários e tags.

Só precisa de uma URL direta da imagem? Enviar para /media. Usar urls.original da resposta. Pronto.

Quer um post compartilhável com comentários e votação? Envie a mídia primeiro e depois chame /posts com os IDs da mídia.

Início Rápido

Envie um único arquivo e receba uma URL direta de CDN. Perfeito para o ShareX, bots do Discord ou qualquer script que só precisa hospedar uma imagem.

Nota: os envios vão para cdn.imgpile.com, não imgpile.com.

curl -X POST https://cdn.imgpile.com/api/v1/media \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]"

Resposta:

{
  "message": "Media created successfully",
  "media": {
    "slug": "abc1234",
    "type": "image/jpeg",
    "urls": {
      "original": "https://cdn.imgpile.com/f/abc1234.jpg",
      ...
    }
  }
}

Envie vários arquivos e, em seguida, agrupe-os em uma postagem com metadados, votação e comentários.

1. Envie cada arquivo para cdn.imgpile.com e mantenha o ID de mídia retornado:

curl -X POST https://cdn.imgpile.com/api/v1/media \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]"
# Returns: { "media": { "id": 12345, ... } }

2. Crie uma postagem com esses IDs:

curl -X POST https://imgpile.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"media_ids": [12345, 12346]}'
# Returns: { "post": { "slug": "xyz789", ... } }

3. (Opcional) Adicione um título e uma descrição:

curl -X PATCH https://imgpile.com/api/v1/posts/xyz789 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My post", "description": "Summer 2026"}'

Sua postagem já está no ar em https://imgpile.com/p/xyz789

Envie uma imagem a partir de um navegador ou Node.js:

const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch('https://cdn.imgpile.com/api/v1/media', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
    },
    body: formData,
});

const { media } = await response.json();
console.log(media.urls.original); // https://cdn.imgpile.com/f/abc1234.jpg

Configuração do ShareX

Baixe a nossa configuração de Custom Uploader e importe no ShareX — não é necessário editar JSON manualmente.

Baixar imgpile.sxcu

Clique no botão acima para baixar imgpile.sxcu.
Dê dois cliques no arquivo — o ShareX vai importá-lo e criar imgpile um uploader disponível.
Abrir Destinations → Custom uploader settings → Headers e substitua YOUR_TOKEN_HERE pelo seu token de API (gere um em Introdução).
Definir Destinations → Image uploader → imgpile. Capture uma captura de tela — a URL vai parar na sua área de transferência como https://cdn.imgpile.com/f/….

Autenticação

Os endpoints de leitura (GET) são públicos e não exigem autenticação. Todos os outros endpoints exigem um token bearer.

curl https://imgpile.com/api/v1/posts

Para requisições autenticadas, envie seu token no Authorization header:

curl -H "Authorization: Bearer YOUR_TOKEN" https://cdn.imgpile.com/api/v1/media -F "[email protected]"

O destino dos envios de arquivo cdn.imgpile.com; veja Media → Upload para mais detalhes.

Gere um token na Introdução seção acima.

Erros

A API retorna códigos de status HTTP padrão. As respostas de erro incluem um corpo JSON com um message (ou error) campo descrevendo o que deu errado.

Códigos de status

Código	Significado
`200`	OK — a requisição foi bem-sucedida
`201`	Created — o recurso foi criado
`400`	Bad Request — requisição malformada
`401`	Unauthenticated — token ausente ou inválido
`403`	Proibido — você não tem permissão para esta ação
`404`	Não encontrado — o recurso não existe
`422`	Validation failed — o corpo da requisição tem campos inválidos
`429`	Rate Limited — muitas requisições, diminua o ritmo
`451`	Unavailable for Legal Reasons — o arquivo correspondeu a um hash banido
`500`	Server Error — algo deu errado do nosso lado

Exemplos de respostas de erro

401 Unauthenticated

{ "message": "Unauthenticated." }

403 Forbidden

{ "message": "This action is unauthorized." }

422 Validation failed

{
  "message": "The file field is required.",
  "errors": {
    "file": ["The file field is required."]
  }
}

429 Rate limited

{ "message": "Too Many Attempts." }

Verifique o Retry-After cabeçalho da resposta pelos segundos até o limite ser redefinido.

451 Conteúdo banido

{ "error": "This file is not allowed." }

Paginação da API

Listar endpoints (GET /posts, GET /media) retornar resultados paginados. O tamanho padrão da página é 10; você pode solicitar até 250 com ?limit=N.

Usar ?page=N para navegar pelas páginas. A resposta inclui metadados de paginação:

{
  "data": [ ... ],
  "links": {
    "first": "https://imgpile.com/api/v1/posts?page=1",
    "last": "https://imgpile.com/api/v1/posts?page=42",
    "prev": null,
    "next": "https://imgpile.com/api/v1/posts?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 10,
    "per_page": 10,
    "total": 421,
    "last_page": 42
  }
}

Ao iterar, siga links.next até que seja null, ou verifique meta.current_page contra meta.last_page.

Filtragem de Conteúdo

Por padrão, listar endpoints (GET /posts, GET /media) retorna apenas conteúdo seguro (status de moderação approved). Para também incluir conteúdo adulto (nsfw), passar ?nsfw=1:

curl https://imgpile.com/api/v1/posts?nsfw=1

Conteúdo banido (rejected, ou seja, spam ou abuso) nunca é retornado para endpoints públicos de feed, independentemente do ?nsfw sinalizador.

Toda resposta de post e de mídia inclui um moderation_status campo para que você possa avisar, desfocar ou ocultar itens sinalizados no seu cliente:

{
  "moderation_status": "approved" | "pending" | "nsfw" | "rejected",
  ...
}

approved — seguro para todos os públicos.
pending — aguardando moderação automatizada.
nsfw — conteúdo adulto; retornado apenas de endpoints públicos quando ?nsfw=1.
rejected — spam/abuso; nunca retornado para endpoints públicos.

Posts ocultos podem ser acessados pelo slug, mas nunca aparecem nos feeds. Posts privados exigem um ?key=xxx parâmetro de consulta (o proprietário pode encontrar isso no link de compartilhamento do post).

Limites de Taxa

Requisições públicas (sem token): 30 requisições/minuto por IP
Requisições autenticadas: 120 requisições/minuto por usuário
Envio de arquivos: 1.000 arquivos/dia por usuário/IP
Tamanho máximo do arquivo: 100 MB
Tipos aceitos: image/* e video/*

Os cabeçalhos de limite de taxa são incluídos em toda resposta (X-RateLimit-Limit, X-RateLimit-Remaining).

O objeto Media

Retornado pelos endpoints de mídia e incorporado nas respostas dos posts.

Campo	Tipo	Descrição
slug	`string`	Identificador único de 7 caracteres. Usado em URLs.
filename	`string`	Nome do arquivo no armazenamento (igual ao slug).
title	`string\|null`	Título fornecido pelo usuário.
description	`string\|null`	Descrição fornecida pelo usuário.
type	`string`	Tipo MIME — por exemplo `image/jpeg`, `video/mp4`.
width	`integer`	Largura em pixels.
height	`integer`	Altura em pixels.
moderation_status	`enum`	Um de `approved`, `pending`, `nsfw`, ou `rejected`. Ver Filtragem de Conteúdo.
processed	`boolean`	`false` enquanto as variantes com tamanhos estão sendo geradas; `true` quando estiver pronto.
created_at	`timestamp`	carimbo de data/hora ISO 8601.
urls	`object`	URLs da CDN em cada tamanho disponível — veja URLs diretas de imagens.
user	`object\|null`	O uploader (username, avatar). Nulo para uploads de convidado.

O objeto Post

Um contêiner compartilhável para um ou mais itens de mídia.

Campo	Tipo	Descrição
id	`integer`	ID numérico. Use `slug` para URLs.
slug	`string`	Identificador único de 7 caracteres. Usado em URLs.
title	`string\|null`	Título do post.
description	`string\|null`	Descrição do post.
score	`integer`	Pontuação líquida de votos (votos a favor menos votos contra).
view_count	`integer`	Total de visualizações de página.
media_count	`integer`	Número de itens de mídia neste post.
moderation_status	`enum`	Um de `approved`, `pending`, `nsfw`, ou `rejected`. Ver Filtragem de Conteúdo.
isUpvotedByUser	`boolean`	Se o usuário autenticado deu upvote neste post.
isDownvotedByUser	`boolean`	Se o usuário autenticado deu downvote neste post.
created_at	`timestamp`	carimbo de data/hora ISO 8601.
user	`object\|null`	O autor (username, avatar). Nulo para posts de convidado.
media	`array`	Array de Objetos de mídia. Incluído apenas em requisições de post único.
first_media	`object\|null`	A primeira mídia (prévia). Incluída apenas nas respostas do feed.
Campos apenas do proprietário (retornados somente ao proprietário do post):
visibility	`enum`	`public`, `hidden`, ou `private`.
access_key	`string\|null`	Necessário para ver um post privado. Anexe como `?key=xxx`.

Endpoints de mídia

Arquivos individuais (imagens ou vídeos). Cada mídia tem uma URL direta da CDN que você pode hotlinkar ou incorporar em qualquer lugar.

POST /media Autenticação necessária

Host de upload

Envie uploads para https://cdn.imgpile.com/api/v1/media — não imgpile.com. Os arquivos são armazenados em uma origem dedicada; fazer POST no host principal vai falhar.

Todos os outros endpoints usam imgpile.com/api/v1 como de costume.

Envie uma imagem ou vídeo. Envie como multipart/form-data.

Parâmetro	Descrição
fileobrigatório	O arquivo para enviar. Máx. 100 MB. Aceita image/* e video/*.
post_idopcional	Anexar a um post existente.

Requisição

curl -X POST https://cdn.imgpile.com/api/v1/media \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]"

Resposta 201

{
  "message": "Media created successfully",
  "media": {
    "slug": "abc1234",
    "filename": "abc1234",
    "type": "image/jpeg",
    "width": 1920,
    "height": 1080,
    "moderation_status": "approved",
    "urls": {
      "original": "https://cdn.imgpile.com/f/abc1234.jpg",
      ...
    }
  }
}

GET /media Público

Liste itens de mídia com filtros e paginação.

Parâmetro	Descrição
tag	Filtrar por nome da tag
sort	`latest` (padrão) ou `random`
period	`day`, `week`, `month`, `year`, `all`
limit	Resultados por página (máx. 250, padrão 10)
username	Filtrar por username
nsfw	Defina como `1` para incluir conteúdo NSFW. Padrão: apenas SFW.

Requisição

curl https://imgpile.com/api/v1/media?limit=20

Resposta 200

{
  "data": [
    {
      "slug": "abc1234",
      "type": "image/jpeg",
      "width": 1920,
      "height": 1080,
      "moderation_status": "approved",
      "urls": { ... }
    },
    ...
  ],
  "links": { ... },
  "meta": { "current_page": 1, "total": 421 }
}

GET /media/{slug} Público

Obtenha um item de mídia único pelo seu slug.

Requisição

curl https://imgpile.com/api/v1/media/abc1234

Resposta 200

{
  "data": {
    "slug": "abc1234",
    "type": "image/jpeg",
    "width": 1920,
    "height": 1080,
    "moderation_status": "approved",
    "urls": { ... }
  }
}

PATCH /media/{slug} Autenticação necessária

Atualize a mídia que você possui.

Parâmetro	Descrição
title	Título da mídia
description	Descrição da mídia

Requisição

curl -X PATCH https://imgpile.com/api/v1/media/abc1234 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "New title"}'

Resposta 200

{
  "message": "Media updated successfully"
}

DELETE /media/{slug} Autenticação necessária

Exclua a mídia que você possui.

Requisição

curl -X DELETE https://imgpile.com/api/v1/media/abc1234 \
  -H "Authorization: Bearer YOUR_TOKEN"

Resposta 200

{
  "message": "Media deleted successfully."
}

Endpoints de posts

Páginas compartilháveis que contêm um ou mais itens de mídia. Têm título, descrição, votação, comentários e tags.

GET /posts Público

Liste posts públicos com filtros e paginação.

Parâmetro	Descrição
tag	Filtrar por nome da tag
sort	`latest` (padrão) ou `random`
period	`day`, `week`, `month`, `year`, `all`
limit	Resultados por página (máx. 250, padrão 10)
username	Filtrar por username
nsfw	Defina como `1` para incluir conteúdo NSFW. Padrão: apenas SFW.

Requisição

curl https://imgpile.com/api/v1/posts?sort=latest

Resposta 200

{
  "data": [
    {
      "id": 30713,
      "slug": "MSGhYqy",
      "title": "Sunset photos",
      "score": 12,
      "view_count": 245,
      "media_count": 3,
      "moderation_status": "approved",
      "user": { "username": "alice", ... },
      "first_media": { ... }
    },
    ...
  ]
}

GET /posts/{slug} Público

Obtenha um único post com mídia paginada.

Parâmetro	Descrição
mediaPage	Número da página para a mídia (padrão 1)
perPage	Itens de mídia por página (padrão 10)
key	Obrigatório para posts privados. O proprietário pode encontrar isso no link de compartilhamento.

Requisição

curl https://imgpile.com/api/v1/posts/MSGhYqy

# Private post with key:
curl "https://imgpile.com/api/v1/posts/xyz789?key=ab12cd34ef"

Resposta 200

{
  "data": {
    "id": 30713,
    "slug": "MSGhYqy",
    "title": "Sunset photos",
    "description": "...",
    "score": 12,
    "view_count": 245,
    "moderation_status": "approved",
    "user": { "username": "alice", ... },
    "media": [ ... ]
  }
}

POST /posts Autenticação necessária

Crie um novo post a partir de mídias enviadas.

Parâmetro	Descrição
media_idsobrigatório	Array de IDs de mídia para incluir no post

Requisição

curl -X POST https://imgpile.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"media_ids": [12345, 12346]}'

Resposta 201

{
  "message": "Post created successfully",
  "post": {
    "id": 30720,
    "slug": "rtWJdHr"
  }
}

PATCH /posts/{slug} Autenticação necessária

Atualize um post que você possui.

Parâmetro	Descrição
title	Título do post (máx. 255)
description	Descrição do post
visibility	`public`, `hidden`, ou `private`. Configuração para `private` gera automaticamente um `access_key`.
is_nsfw	Booleano. Marque o post como conteúdo adulto para que ele fique bloqueado pelo botão NSFW do visualizador. Depois de definido, o post não será resolvido automaticamente abaixo `nsfw`.
media_order	Array de slugs de mídia na ordem desejada

Requisição

curl -X PATCH https://imgpile.com/api/v1/posts/rtWJdHr \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated title", "visibility": "private"}'

Resposta 200

{
  "message": "Post updated successfully",
  "visibility": "private",
  "access_key": "ab12cd34ef"
}

DELETE /posts/{slug} Autenticação necessária

Exclua um post que você possui.

Requisição

curl -X DELETE https://imgpile.com/api/v1/posts/rtWJdHr \
  -H "Authorization: Bearer YOUR_TOKEN"

Resposta 200

{
  "message": "Post deleted successfully"
}

Comentários

POST /posts/{post}/comments Autenticação necessária

Adicione um comentário a um post.

Parâmetro	Descrição
contentobrigatório	Texto do comentário (máx. 500 caracteres)
parent_idopcional	ID do comentário para responder (para respostas em threads)

Requisição

curl -X POST https://imgpile.com/api/v1/posts/MSGhYqy/comments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Nice shot!"}'

Resposta 201

{
  "success": true,
  "comment": {
    "id": 456,
    "content": "Nice shot!",
    "user_id": 1,
    "post_id": 12345
  }
}

DELETE /comments/{comment} Autenticação necessária

Exclua um comentário que você possui.

Requisição

curl -X DELETE https://imgpile.com/api/v1/comments/123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Resposta 200

{
  "success": true,
  "message": "Comment deleted successfully"
}

Usuários

GET /users/{username}/posts Público

Obtenha os posts de um usuário.

Requisição

curl https://imgpile.com/api/v1/users/alice/posts

Resposta 200

{
  "data": [
    {
      "id": 30713,
      "slug": "MSGhYqy",
      "title": "Sunset photos",
      "score": 12,
      "moderation_status": "approved",
      "first_media": { ... }
    },
    ...
  ]
}

GET /users/{username}/media Público

Obtenha a mídia de um usuário.

Requisição

curl https://imgpile.com/api/v1/users/alice/media

Resposta 200

{
  "data": [
    {
      "slug": "abc1234",
      "type": "image/jpeg",
      "moderation_status": "approved",
      "urls": { ... }
    },
    ...
  ]
}

GET /users/{username}/comments Público

Obtenha os comentários de um usuário (paginado).

Requisição

curl https://imgpile.com/api/v1/users/alice/comments

GET /users/{username}/followers Público

Obtenha os seguidores de um usuário (paginado).

Requisição

curl https://imgpile.com/api/v1/users/alice/followers

GET /users/{username}/following Público

Obtenha os usuários que este usuário está seguindo (paginado).

Requisição

curl https://imgpile.com/api/v1/users/alice/following

POST /users/{username}/follow Autenticação necessária

Siga um usuário.

Requisição

curl -X POST https://imgpile.com/api/v1/users/alice/follow \
  -H "Authorization: Bearer YOUR_TOKEN"

Resposta 200

{
  "message": "User followed."
}

DELETE /users/{username}/follow Autenticação necessária

Deixe de seguir um usuário.

Requisição

curl -X DELETE https://imgpile.com/api/v1/users/alice/follow \
  -H "Authorization: Bearer YOUR_TOKEN"

Resposta 200

{
  "message": "User unfollowed."
}

Votação

POST /posts/{post}/upvote Autenticação necessária

Votar positivamente em um post. Chamando novamente remove o voto positivo.

Requisição

curl -X POST https://imgpile.com/api/v1/posts/123/upvote \
  -H "Authorization: Bearer YOUR_TOKEN"

Resposta 200

{
  "message": "Post upvoted successfully",
  "score": 13
}

POST /posts/{post}/downvote Autenticação necessária

Votar negativamente em um post. Chamando novamente remove o voto negativo.

Requisição

curl -X POST https://imgpile.com/api/v1/posts/123/downvote \
  -H "Authorization: Bearer YOUR_TOKEN"

Resposta 200

{
  "message": "Post downvoted successfully",
  "score": 11
}

POST /comments/{comment}/upvote Autenticação necessária

Votar positivamente em um comentário. Chamando novamente remove o voto positivo.

Requisição

curl -X POST https://imgpile.com/api/v1/comments/456/upvote \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /comments/{comment}/downvote Autenticação necessária

Votar negativamente em um comentário. Chamando novamente remove o voto negativo.

Requisição

curl -X POST https://imgpile.com/api/v1/comments/456/downvote \
  -H "Authorization: Bearer YOUR_TOKEN"

URLs diretas de imagens

Todos os arquivos enviados são servidos via a CDN. A resposta da mídia inclui um urls objeto com todos os tamanhos disponíveis:

https://cdn.imgpile.com/f/{filename}.{ext}          — Original
https://cdn.imgpile.com/f/{filename}_xs.{ext}       — Extra small
https://cdn.imgpile.com/f/{filename}_sm.{ext}       — Small
https://cdn.imgpile.com/f/{filename}_md.{ext}       — Medium
https://cdn.imgpile.com/f/{filename}_lg.{ext}       — Large
https://cdn.imgpile.com/f/{filename}_xl.{ext}       — Extra large
https://cdn.imgpile.com/f/{filename}_thumb.jpg      — Thumbnail (videos)