Tài liệu API — PhotoRestore

Bản beta riêng tư

Các endpoint này đang hoạt động trong bản xem trước nhưng chưa công khai — chưa có việc cấp khóa API, và hình dạng có thể còn thay đổi trước bản chính thức.

Tham gia danh sách chờ API

Tổng quan

Ứng dụng này cung cấp một API tác vụ nhỏ, cùng nguồn: tải lên ảnh, gửi tác vụ phục hồi hoặc nâng cấp, rồi theo dõi kết quả. Chưa có khóa API — mọi yêu cầu được giới hạn theo cookie phiên khách của trình duyệt bạn.

URL gốc: /apiMọi đường dẫn bên dưới đều tương đối so với URL gốc cùng nguồn này — không có máy chủ API riêng nào cần cấu hình.
Xác thực: Giới hạn theo phiên qua cookie httpOnly được cấp khi tiếp tục với tư cách khách. Chưa có khóa API nào tồn tại (xem mục "Kế hoạch" bên dưới).

Cam kết hợp đồng: result_url của một tác vụ luôn là một image_url hợp lệ — bạn có thể gửi trực tiếp nó tới /api/restore hoặc /api/upscale để nối tiếp một thao tác khác (đây chính xác là cách "Nâng cấp ảnh này" hoạt động sau khi Phục hồi).

POST/api/uploads

Tải lên một ảnh

Tải lên một tệp ảnh duy nhất và trả về URL tài nguyên cùng nguồn mà bạn có thể dùng làm image_url cho Phục hồi hoặc Nâng cấp.

Nội dung yêu cầu

Tên	Kiểu	Bắt buộc	Giới hạn	Mô tả
file	binary (multipart/form-data)	Có	—	Tệp ảnh, được gửi dưới dạng multipart/form-data.

Nội dung phản hồi

Tên	Kiểu	Bắt buộc	Giới hạn	Mô tả
image_url	string	Có	—	URL tài nguyên cùng nguồn được trả về từ một lần tải lên trước đó — hình dạng image_url duy nhất được chấp nhận.
bytes	number	Có	0–9007199254740991	Kích thước tệp đã lưu, tính bằng byte.
mime	string	Có	—	Kiểu MIME được nhận diện của tệp đã lưu (có giá trị quyết định — không phải kiểu do client khai báo).

Ví dụ phản hồi 201

{
  "image_url": "/api/mock-assets/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "bytes": 2458112,
  "mime": "image/jpeg"
}

Mẫu mã

curl -X POST 'https://your-app.example.com/api/uploads' \
  -F "file=@photo.jpg"

POST/api/restore

Tạo tác vụ phục hồi

Bắt đầu một tác vụ phục hồi bất đồng bộ cho ảnh đã tải lên trước đó. Trả về ngay một tham chiếu tác vụ ở trạng thái pending — theo dõi tiến trình bằng GET /api/jobs/{job_id}.

Nội dung yêu cầu

Tên	Kiểu	Bắt buộc	Giới hạn	Mô tả
image_url	string	Có	/api/mock-assets/<uuid>	URL tài nguyên cùng nguồn được trả về từ một lần tải lên trước đó — hình dạng image_url duy nhất được chấp nhận.
user_hint	string	Không	max 300 chars	Một ghi chú văn bản tùy chọn mô tả ảnh, dùng để định hướng bước phân tích giả lập.
params.colorize	boolean	Có	—	Bắt buộc để tương thích lược đồ. Giá trị được chấp nhận nhưng không chọn chế độ xử lý — tiến trình phục hồi là như nhau với mọi giá trị.
params.resolution	unknown	Có	—
params.variant	unknown	Có	—

Nội dung phản hồi

Tên	Kiểu	Bắt buộc	Giới hạn	Mô tả
job_id	string	Có	job_<uuid>	Định danh duy nhất của tác vụ này.
status	pending \| processing \| succeeded \| failed \| cancelled	Có	—	Trạng thái vòng đời hiện tại của tác vụ.

Ví dụ phản hồi 202

{
  "job_id": "job_3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "pending"
}

Mẫu mã

curl -X POST 'https://your-app.example.com/api/restore' \
  -H 'Content-Type: application/json' \
  -d '{  "image_url": "/api/mock-assets/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",  "user_hint": "the sky was blue",  "params": {    "colorize": true  }}'

POST/api/upscale

Tạo tác vụ nâng cấp

Bắt đầu một tác vụ nâng cấp bất đồng bộ cho ảnh đã tải lên trước đó, theo chế độ và độ phân giải mục tiêu yêu cầu. Trả về ngay một tham chiếu tác vụ ở trạng thái pending.

Nội dung yêu cầu

Tên	Kiểu	Bắt buộc	Giới hạn	Mô tả
image_url	string	Có	/api/mock-assets/<uuid>	URL tài nguyên cùng nguồn được trả về từ một lần tải lên trước đó — hình dạng image_url duy nhất được chấp nhận.
user_hint	string	Không	max 300 chars	Một ghi chú văn bản tùy chọn mô tả ảnh, dùng để định hướng bước phân tích giả lập.
params.mode	fast \| balanced \| high	Có	—	Sự đánh đổi giữa chất lượng và tốc độ khi nâng cấp.
params.target_megapixels	number	Có	1–64	Độ phân giải đầu ra mong muốn, tính bằng megapixel.

Nội dung phản hồi

Tên	Kiểu	Bắt buộc	Giới hạn	Mô tả
job_id	string	Có	job_<uuid>	Định danh duy nhất của tác vụ này.
status	pending \| processing \| succeeded \| failed \| cancelled	Có	—	Trạng thái vòng đời hiện tại của tác vụ.

Ví dụ phản hồi 202

{
  "job_id": "job_3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "pending"
}

Mẫu mã

curl -X POST 'https://your-app.example.com/api/upscale' \
  -H 'Content-Type: application/json' \
  -d '{  "image_url": "/api/mock-assets/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",  "params": {    "mode": "fast",    "target_megapixels": 12  }}'

GET/api/jobs/{job_id}

Lấy trạng thái tác vụ

Trả về trạng thái hiện tại của một tác vụ: status, progress, và — khi succeeded — một result_url bạn có thể tải xuống hoặc gửi lại như một image_url mới.

Nội dung phản hồi

Tên	Kiểu	Bắt buộc	Giới hạn	Mô tả
job_id	string	Có	job_<uuid>	Định danh duy nhất của tác vụ này.
type	restore \| upscale	Có	—	Công cụ nào đã tạo ra tác vụ này.
status	pending \| processing \| succeeded \| failed \| cancelled	Có	—	Trạng thái vòng đời hiện tại của tác vụ.
progress	number	Có	0–100	Phần trăm hoàn thành, từ 0–100.
result_url	string	Không	—	Xuất hiện khi tác vụ thành công — một URL tài nguyên cùng nguồn cũng có thể được gửi lại như một image_url mới.
result_urls.light	string	Có	—
result_urls.strong	string	Không	—
before_url	string	Không	—
error.code	INVALID_REQUEST \| UNSUPPORTED_FORMAT \| FILE_TOO_LARGE \| JOB_NOT_FOUND \| VLM_FAILED \| WORKFLOW_FAILED \| TIMEOUT \| CANCELLED \| INTERNAL \| INSUFFICIENT_CREDITS \| STORAGE_QUOTA_EXCEEDED	Có	—	Lý do thất bại có thể đọc bằng máy.
error.message	string	Có	—	Thông báo thất bại dễ đọc cho con người. Chỉ xuất hiện khi status là failed.
created_at	string	Có	—	Thời điểm tác vụ được tạo, theo định dạng ISO 8601.
updated_at	string	Có	—	Thời điểm tác vụ được cập nhật lần cuối, theo định dạng ISO 8601.

Ví dụ phản hồi 200

{
  "job_id": "job_3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "restore",
  "status": "succeeded",
  "progress": 100,
  "result_url": "/api/mock-assets/6c1d3a2e-4f5b-4a1e-9c2d-1a2b3c4d5e6f",
  "created_at": "2026-08-03T10:15:00.000Z",
  "updated_at": "2026-08-03T10:15:42.000Z"
}

Mẫu mã

curl -X GET 'https://your-app.example.com/api/jobs/job_3fa85f64-5717-4562-b3fc-2c963f66afa6'

POST/api/jobs/{job_id}/cancel

Hủy tác vụ

Yêu cầu hủy một tác vụ. Hủy một tác vụ đã ở trạng thái cuối là một thao tác không tác dụng, trả về trạng thái hiện tại không đổi.

Nội dung phản hồi

Tên	Kiểu	Bắt buộc	Giới hạn	Mô tả
job_id	string	Có	job_<uuid>	Định danh duy nhất của tác vụ này.
status	pending \| processing \| succeeded \| failed \| cancelled	Có	—	Trạng thái vòng đời hiện tại của tác vụ.

Ví dụ phản hồi 202

{
  "job_id": "job_3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "cancelled"
}

Mẫu mã

curl -X POST 'https://your-app.example.com/api/jobs/job_3fa85f64-5717-4562-b3fc-2c963f66afa6/cancel'

Vòng đời trạng thái tác vụ

Mỗi tác vụ đi qua cỗ máy trạng thái này. pending và processing là trạng thái chưa kết thúc; succeeded, failed và cancelled là trạng thái cuối và không bao giờ thay đổi nữa.

pendingprocessingsucceededfailedcancelled

Nếu một tác vụ không đạt trạng thái cuối trong thời hạn theo dõi của client, nó được xem là thất bại TIMEOUT.

Mã lỗi

Mọi lỗi đều dùng bộ mã cố định này. INVALID_REQUEST, UNSUPPORTED_FORMAT, FILE_TOO_LARGE và JOB_NOT_FOUND được trả về dưới dạng phản hồi lỗi HTTP; các mã còn lại xuất hiện dưới dạng error.code bên trong đối tượng tác vụ khi tác vụ đó đạt trạng thái cuối failed hoặc cancelled.

Mã	Xuất hiện ở đâu	Ý nghĩa
INVALID_REQUEST	Phản hồi lỗi HTTP 400	Yêu cầu này không hợp lệ. Vui lòng kiểm tra thông tin nhập và thử lại.
UNSUPPORTED_FORMAT	Phản hồi lỗi HTTP 415	Định dạng tệp này không được hỗ trợ. Vui lòng dùng JPEG, PNG, WebP, HEIC hoặc HEIF.
FILE_TOO_LARGE	Phản hồi lỗi HTTP 413	Tệp này quá lớn. Vui lòng dùng ảnh nhỏ hơn.
JOB_NOT_FOUND	Phản hồi lỗi HTTP 404	Chúng tôi không tìm thấy công việc này. Có thể nó đã hết hạn.
VLM_FAILED	Bên trong trường error của một tác vụ ở trạng thái cuối	Chúng tôi không thể phân tích ảnh này. Vui lòng thử lại.
WORKFLOW_FAILED	Bên trong trường error của một tác vụ ở trạng thái cuối	Xử lý thất bại. Vui lòng thử lại.
TIMEOUT	Bên trong trường error của một tác vụ ở trạng thái cuối	Việc này đang mất nhiều thời gian hơn dự kiến. Vui lòng thử lại.
CANCELLED	Bên trong trường error của một tác vụ ở trạng thái cuối	Công việc này đã bị hủy.
INTERNAL	Phản hồi lỗi HTTP 500	Đã xảy ra sự cố ở phía chúng tôi. Vui lòng thử lại.
INSUFFICIENT_CREDITS	Phản hồi lỗi HTTP 402	Bạn không có đủ tín dụng cho công việc này. Nạp thêm để tiếp tục.
STORAGE_QUOTA_EXCEEDED	Phản hồi lỗi HTTP 413	Album của bạn đã đầy. Hãy xóa bớt ảnh hoặc nâng cấp để tiếp tục.

Kế hoạch: một API công khai có phiên bản

Một cổng /v1 có phiên bản cho tích hợp bên thứ ba đang được lên kế hoạch — khóa API thay cho cookie phiên, webhook khi tác vụ hoàn thành thay cho việc theo dõi liên tục, và giới hạn tốc độ theo từng khóa. Không có điều nào trong số này được triển khai, và không có hình dạng yêu cầu/phản hồi, cơ chế xác thực, chữ ký webhook hay con số giới hạn tốc độ nào được cam kết. Hãy xem mọi thứ ở trên mục này — các endpoint /api cùng nguồn mà ứng dụng này thực sự cung cấp — là hợp đồng duy nhất có hiệu lực hôm nay. Nếu /v1 ra mắt, nó sẽ được tài liệu hóa riêng với một đặc tả đầy đủ; đoạn này chỉ là một lời báo trước, không phải bản xem trước.

Trong trang này

Tổng quan

Tải lên một ảnh

Nội dung yêu cầu

Nội dung phản hồi

Ví dụ phản hồi 201

Mẫu mã

Tạo tác vụ phục hồi

Nội dung yêu cầu

Nội dung phản hồi

Ví dụ phản hồi 202

Mẫu mã

Tạo tác vụ nâng cấp

Nội dung yêu cầu

Nội dung phản hồi

Ví dụ phản hồi 202

Mẫu mã

Lấy trạng thái tác vụ

Nội dung phản hồi

Ví dụ phản hồi 200

Mẫu mã

Hủy tác vụ

Nội dung phản hồi

Ví dụ phản hồi 202

Mẫu mã

Vòng đời trạng thái tác vụ

Mã lỗi