Logotipo do Foto para URL

Documentação da API

O acesso à API exige assinatura ativa Pro ou Premium. Autentique com uma chave de API e envie imagens para a mesma biblioteca do Painel. As cotas seguem o plano pago no site.

Imagens de produto

Enviar uma imagem

POST /api/v1/upload com multipart/form-data.

Parâmetros

Authorization
Obrigatório. Cabeçalho do pedido. Formato: Bearer A_SUA_CHAVE_API.
file
Obrigatório. Um ficheiro binário ou dados em base64.
name
Opcional. Nome do ficheiro; detetado automaticamente no upload multipart local.

Pedido de exemplo

Ficheiro binário

curl https://phototourl.com/api/v1/upload \
  -X POST \
  -H "Authorization: Bearer ptu_live_YOUR_KEY" \
  -F "file=@./product.jpg"

Base64

curl https://phototourl.com/api/v1/upload \
  -X POST \
  -H "Authorization: Bearer ptu_live_YOUR_KEY" \
  -F "file=R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" \
  -F "name=pixel.gif"

Para enviar um ficheiro local use sempre POST. GET não é suportado para upload.

Campos da resposta

id
Id do recurso na sua biblioteca.
url
URL CDN para usar em páginas de produto.
fileName
Nome de ficheiro original.
fileSize
Tamanho do ficheiro em bytes.
mimeType
Tipo MIME do ficheiro enviado.
createdAt
Horário do envio em UTC, no formato YYYY-MM-DD HH:mm:ss.
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://cdn.phototourl.com/pro/2026-11-05-a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
  "fileName": "product.jpg",
  "fileSize": 128472,
  "mimeType": "image/jpeg",
  "createdAt": "2026-11-05 10:20:30"
}

Listar imagens

GET /api/v1/images com page e pageSize opcionais (máx. 100).

curl "https://phototourl.com/api/v1/images?page=1&pageSize=20" \
  -H "Authorization: Bearer ptu_live_YOUR_KEY"

Campos da resposta

resources
Array de imagens: id, fileName, url, fileSize, mimeType, createdAt.
page
Número da página atual.
pageSize
Itens por página.
total
Total de imagens na biblioteca.
{
  "resources": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "fileName": "product.jpg",
      "url": "https://cdn.phototourl.com/pro/2026-11-05-a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
      "fileSize": 128472,
      "mimeType": "image/jpeg",
      "createdAt": "2026-11-05 10:20:30"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1
}

Excluir uma imagem

DELETE /api/v1/images/:id. Remove o arquivo do armazenamento e da sua biblioteca.

curl -X DELETE https://phototourl.com/api/v1/images/RESOURCE_ID \
  -H "Authorization: Bearer ptu_live_YOUR_KEY"

Campos da resposta

success
true quando a imagem foi excluída.
{ "success": true }

Limites

API indisponível no Free. Pro e Premium usam os limites de upload, armazenamento e tamanho de arquivo do plano. Ao exceder um limite, a API retorna erro com upgradeUrl.

Erros

Requisições com falha retornam um código de erro. Erros de cota podem incluir upgradeUrl.

  • dailyLimitReached— Limite diário de envio atingido (HTTP 429).
  • storageLimitReached— Cota de armazenamento excedida (HTTP 413).
  • fileTooLarge— Arquivo maior do que o plano permite (HTTP 400).
  • 401— Chave de API ausente, inválida ou revogada.
{
  "error": "dailyLimitReached",
  "errorParams": { "limit": 1000 },
  "plan": "paid",
  "limit": 1000,
  "upgradeUrl": "https://www.phototourl.com/pricing"
}