PhotoRestore

개요

이 앱은 작지만 동일 출처의 작업 API를 제공합니다: 이미지를 업로드하고, 복원 또는 업스케일 작업을 제출한 뒤, 결과를 폴링합니다. 아직 API 키는 없으며 — 모든 요청은 브라우저의 게스트 세션 쿠키 범위로 제한됩니다.

기본 URL
/api아래의 모든 경로는 이 동일 출처 기본 URL을 기준으로 한 상대 경로입니다 — 별도로 설정할 API 호스트는 없습니다.
인증
게스트로 계속하기를 통해 발급된 httpOnly 쿠키로 세션 범위가 지정됩니다. 아직 API 키는 존재하지 않습니다 (아래 "계획" 참고).

계약 보장 사항: 작업의 result_url은 항상 유효한 image_url입니다 — 이를 /api/restore 또는 /api/upscale에 그대로 제출해 다른 작업으로 이어갈 수 있습니다 (복원 후 "이 이미지 업스케일하기"가 정확히 이런 방식으로 동작합니다).

POST/api/uploads

이미지 업로드

이미지 파일 하나를 업로드하고, Restore 또는 Upscale에 image_url로 전달할 수 있는 동일 출처 자산 URL을 반환합니다.

요청 본문

이름타입필수범위설명
filebinary (multipart/form-data)예—multipart/form-data로 전송되는 이미지 파일입니다.

응답 본문

이름타입필수범위설명
image_urlstring예—이전 업로드에서 반환된 동일 출처 자산 URL입니다 — 허용되는 유일한 image_url 형태입니다.
bytesnumber예0–9007199254740991저장된 파일 크기(바이트)입니다.
mimestring예—저장된 파일에서 감지된 MIME 타입입니다 (권위 있는 값 — 클라이언트가 선언한 타입이 아닙니다).

201 응답 예시

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

코드 샘플

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

복원 작업 생성

이전에 업로드한 이미지에 대해 비동기 복원 작업을 시작합니다. pending 상태의 작업 참조를 즉시 반환하며 — GET /api/jobs/{job_id}로 진행 상황을 폴링하세요.

요청 본문

이름타입필수범위설명
image_urlstring예/api/mock-assets/<uuid>이전 업로드에서 반환된 동일 출처 자산 URL입니다 — 허용되는 유일한 image_url 형태입니다.
user_hintstring아니요max 300 chars사진을 설명하는 선택적 자유 텍스트 메모로, 모의 분석 단계를 유도하는 데 사용됩니다.
params.colorizeboolean예—스키마 호환성을 위해 필수입니다. 값은 허용되지만 처리 모드를 선택하지는 않으며, 어느 값이든 복원 파이프라인은 동일합니다.
params.resolutionunknown예—
params.variantunknown예—

응답 본문

이름타입필수범위설명
job_idstring예job_<uuid>이 작업의 고유 식별자입니다.
statuspending | processing | succeeded | failed | cancelled예—작업의 현재 생명주기 상태입니다.

202 응답 예시

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

코드 샘플

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

업스케일 작업 생성

이전에 업로드한 이미지에 대해 요청한 모드와 목표 해상도로 비동기 업스케일 작업을 시작합니다. pending 상태의 작업 참조를 즉시 반환합니다.

요청 본문

이름타입필수범위설명
image_urlstring예/api/mock-assets/<uuid>이전 업로드에서 반환된 동일 출처 자산 URL입니다 — 허용되는 유일한 image_url 형태입니다.
user_hintstring아니요max 300 chars사진을 설명하는 선택적 자유 텍스트 메모로, 모의 분석 단계를 유도하는 데 사용됩니다.
params.modefast | balanced | high예—업스케일의 품질/속도 절충입니다.
params.target_megapixelsnumber예1–64원하는 출력 해상도(메가픽셀)입니다.

응답 본문

이름타입필수범위설명
job_idstring예job_<uuid>이 작업의 고유 식별자입니다.
statuspending | processing | succeeded | failed | cancelled예—작업의 현재 생명주기 상태입니다.

202 응답 예시

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

코드 샘플

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}

작업 상태 조회

작업의 현재 상태를 반환합니다: status, progress, 그리고 succeeded 상태가 되면 다운로드하거나 새 image_url로 다시 제출할 수 있는 result_url.

응답 본문

이름타입필수범위설명
job_idstring예job_<uuid>이 작업의 고유 식별자입니다.
typerestore | upscale예—이 작업을 생성한 도구입니다.
statuspending | processing | succeeded | failed | cancelled예—작업의 현재 생명주기 상태입니다.
progressnumber예0–100완료 비율(0~100)입니다.
result_urlstring아니요—작업이 성공하면 나타나며 — 새 image_url로도 제출할 수 있는 동일 출처 자산 URL입니다.
result_urls.lightstring예—
result_urls.strongstring아니요—
before_urlstring아니요—
error.codeINVALID_REQUEST | UNSUPPORTED_FORMAT | FILE_TOO_LARGE | JOB_NOT_FOUND | VLM_FAILED | WORKFLOW_FAILED | TIMEOUT | CANCELLED | INTERNAL | INSUFFICIENT_CREDITS | STORAGE_QUOTA_EXCEEDED예—기계가 읽을 수 있는 실패 원인입니다.
error.messagestring예—사람이 읽을 수 있는 실패 메시지입니다. status가 failed일 때만 존재합니다.
created_atstring예—작업이 생성된 시각(ISO 8601)입니다.
updated_atstring예—작업이 마지막으로 업데이트된 시각(ISO 8601)입니다.

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"
}

코드 샘플

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

작업 취소

작업 취소를 요청합니다. 이미 종료 상태인 작업을 취소하면 아무 효과 없이 현재 상태를 그대로 반환합니다.

응답 본문

이름타입필수범위설명
job_idstring예job_<uuid>이 작업의 고유 식별자입니다.
statuspending | processing | succeeded | failed | cancelled예—작업의 현재 생명주기 상태입니다.

202 응답 예시

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

코드 샘플

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

작업 상태 생명주기

모든 작업은 이 상태 기계를 거칩니다. pending과 processing은 비종료 상태이며, succeeded, failed, cancelled는 종료 상태로 다시는 변경되지 않습니다.

pendingprocessingsucceededfailedcancelled

작업이 클라이언트의 폴링 기한 내에 종료 상태에 도달하지 못하면 TIMEOUT 실패로 처리됩니다.

오류 코드

모든 오류는 이 고정된 코드 집합을 사용합니다. INVALID_REQUEST, UNSUPPORTED_FORMAT, FILE_TOO_LARGE, JOB_NOT_FOUND는 HTTP 오류 응답으로 반환되며, 나머지는 해당 작업이 failed 또는 cancelled 종료 상태에 도달했을 때 작업 객체 내부의 error.code로 나타납니다.

코드나타나는 위치의미
INVALID_REQUESTHTTP 400 오류 응답요청이 유효하지 않습니다. 입력 내용을 확인한 후 다시 시도해 주세요.
UNSUPPORTED_FORMATHTTP 415 오류 응답지원되지 않는 파일 형식입니다. JPEG, PNG, WebP, HEIC, HEIF 중 하나를 사용해 주세요.
FILE_TOO_LARGEHTTP 413 오류 응답파일이 너무 큽니다. 더 작은 이미지를 사용해 주세요.
JOB_NOT_FOUNDHTTP 404 오류 응답이 작업을 찾을 수 없습니다. 만료되었을 수 있습니다.
VLM_FAILED종료된 작업의 error 필드 내부이 이미지를 분석할 수 없습니다. 다시 시도해 주세요.
WORKFLOW_FAILED종료된 작업의 error 필드 내부처리에 실패했습니다. 다시 시도해 주세요.
TIMEOUT종료된 작업의 error 필드 내부예상보다 시간이 오래 걸리고 있습니다. 다시 시도해 주세요.
CANCELLED종료된 작업의 error 필드 내부이 작업은 취소되었습니다.
INTERNALHTTP 500 오류 응답저희 쪽에서 문제가 발생했습니다. 다시 시도해 주세요.
INSUFFICIENT_CREDITSHTTP 402 오류 응답이 작업을 진행할 크레딧이 부족합니다. 충전 후 계속하세요.
STORAGE_QUOTA_EXCEEDEDHTTP 413 오류 응답앨범이 가득 찼습니다. 사진을 삭제하거나 업그레이드하여 계속하세요.