Logotip de Foto a URL

Documentació de l'API

L'accés a l'API requereix una subscripció Pro o Premium activa. Autentica't amb una clau API i puja imatges a la mateixa biblioteca que veus al tauler. Les quotes coincideixen amb el teu pla de pagament al web.

Imatges de producte

Pujar una imatge

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

Paràmetres

Authorization
Obligatori. Capçalera de la petició. Format: Bearer LA_VOSTRA_CLAU_API.
file
Obligatori. Un fitxer binari o dades en base64.
name
Opcional. Nom del fitxer; es detecta automàticament en una pujada multipart local.

Exemple de sol·licitud

Fitxer binari

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"

Per pujar un fitxer local useu sempre POST. GET no és compatible.

Camps de la resposta

id
Identificador del recurs a la teva biblioteca.
url
URL CDN per a pàgines de producte.
fileName
Nom de fitxer original.
fileSize
Mida del fitxer en bytes.
mimeType
Tipus MIME del fitxer pujat.
createdAt
Hora de pujada en UTC, format 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"
}

Llistar imatges

GET /api/v1/images amb page i pageSize opcionals (màx. 100).

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

Camps de la resposta

resources
Array d'imatges: id, fileName, url, fileSize, mimeType, createdAt.
page
Número de pàgina actual.
pageSize
Elements per pàgina.
total
Total d'imatges a la 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
}

Eliminar una imatge

DELETE /api/v1/images/:id. Elimina el fitxer de l'emmagatzematge i de la biblioteca.

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

Camps de la resposta

success
true quan s'ha eliminat la imatge.
{ "success": true }

Límits

L'API no està disponible al pla gratuït. Pro i Premium usen els límits de pujada, emmagatzematge i mida de fitxer del teu pla. Si els superes, l'API retorna un error amb upgradeUrl.

Errors

Les sol·licituds fallides retornen un codi d'error. Els errors de quota poden incloure upgradeUrl.

  • dailyLimitReached— S'ha assolit el límit diari de pujades (HTTP 429).
  • storageLimitReached— S'ha superat la quota d'emmagatzematge (HTTP 413).
  • fileTooLarge— El fitxer és més gran del que permet el pla (HTTP 400).
  • 401— Clau API absent, no vàlida o revocada.
{
  "error": "dailyLimitReached",
  "errorParams": { "limit": 1000 },
  "plan": "paid",
  "limit": 1000,
  "upgradeUrl": "https://www.phototourl.com/pricing"
}