Skip to content
tutu.to

API v2 Reference

REST
Authenticate with the API key that owns the images. Send it in Authorization: Bearer YOUR_API_KEY or X-Tutu-API-Key. Keep private keys on trusted clients.
Create an API key

Upload endpoints

  • POST /api/2/upload: multipart image upload. Use the source field.
  • POST /api/2/urlUpload: fetch and upload a remote image using imgUrl.
  • POST /api/2/d: legacy-compatible remote download/upload endpoint; keep existing clients on their current request shape.

Assign an upload to an album

For /upload, /urlUpload, and POST /d, send both album_id and the current album_privacy snapshot. The server rechecks ownership and privacy in the image transaction. A changed or dissolved target returns ALBUM_STATE_CHANGED or ALBUM_NOT_FOUND; do not retry it with a different upload ID automatically.

Account album endpoints

These endpoints operate only on images owned by the authenticated API key. List results are paginated; management responses are private and not cacheable.
Method and pathPurpose
GET /api/2/accountCheck account identity and album capabilities.
GET /api/2/albumsList albums; supports page, per_page, and q.
POST /api/2/albumsCreate an album with name, description, and privacy.
GET /api/2/albums/{id}Read an owned album and its current state token.
PATCH /api/2/albums/{id}Edit album fields; include state_token. Widening visibility requires explicit exposure confirmation.
GET /api/2/imagesBrowse owned images with page, per_page, album_id, or q filters.
POST /api/2/images/move/previewPreview a move using image IDs and nullable album_id.
POST /api/2/images/moveCommit the preview using state_token and any confirmation token.
POST /api/2/albums/{id}/dissolve/previewPreview effects before dissolving; images are retained.
POST /api/2/albums/{id}/dissolveDissolve an album using its current state token.
POST /api/2/uploads/statusRecover the result for a fixed upload ID and created_at timestamp.

Idempotency and recovery

Every album mutation requires a UUID Idempotency-Key and a canonical UTC, second-precision X-Client-Operation-Created-At header. Keep both values unchanged when retrying the same operation. Successful results are recoverable for 24 hours, including after Redis state loss.
curl -X POST https://tutu.to/api/2/albums \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000' \
  -H 'X-Client-Operation-Created-At: 2026-10-16T08:30:00Z' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Travel","description":"2026 trip","privacy":"private_but_link"}'
For upload recovery, send {"upload_id":"…","created_at":"…"} to POST /api/2/uploads/status. An unknown result may be retried with the same operation context; OPERATION_EXPIRED means the server will not execute that old operation again.
Exposure changes require a fresh preview and confirmation. Protected legacy albums cannot be selected as new upload targets, and dissolving an album never deletes its images or changes their intrinsic visibility.