API v2 Reference
REST
Authenticate with the API key that owns the images. Send it in
Create an API keyAuthorization: Bearer YOUR_API_KEY or X-Tutu-API-Key. Keep private keys on trusted clients.Upload endpoints
POST /api/2/upload: multipart image upload. Use thesourcefield.POST /api/2/urlUpload: fetch and upload a remote image usingimgUrl.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.Link-only visibility
private_but_link albums are excluded from public discovery. Anyone with a known album or image link can still access content according to the image’s own visibility. This is not password protection.
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 path | Purpose |
|---|---|
GET /api/2/account | Check account identity and album capabilities. |
GET /api/2/albums | List albums; supports page, per_page, and q. |
POST /api/2/albums | Create 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/images | Browse owned images with page, per_page, album_id, or q filters. |
POST /api/2/images/move/preview | Preview a move using image IDs and nullable album_id. |
POST /api/2/images/move | Commit the preview using state_token and any confirmation token. |
POST /api/2/albums/{id}/dissolve/preview | Preview effects before dissolving; images are retained. |
POST /api/2/albums/{id}/dissolve | Dissolve an album using its current state token. |
POST /api/2/uploads/status | Recover 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.