ID PhotoREST · JSONOpenAPI 3.1

SVOYAGER ID Photo API

어떤 사진이든 규정을 준수하는 신분증/여권/비자용 사진으로 변환합니다.

SVOYAGER의 ID Photo API는 일반 인물 사진을 규정 준수 문서용 사진으로 변환합니다. ID Photo는 단일 제품입니다. 여권, 비자, 거주 허가증 및 주민등록증은 별도의 제품이 아닌 문서 사양으로 표시됩니다. 사진을 업로드하고, 규격에 맞춰 워터마크가 포함된 미리보기를 생성한 후, 최종 확정을 통해 워터마크가 없는 결과물을 얻을 수 있습니다.

미리 보기 → 최종 워크플로우

1사진 업로드. 업로드 대상을 생성하고 해당 대상으로 이미지 바이트를 전송하십시오.
2세션 생성. 사양에 따라 워터마크가 적용된 미리보기를 렌더링하십시오. 반환된 문제점을 검토하십시오.
3최종 확정. 검토된 세션을 주문으로 전환하고 워터마크가 없는 최종 파일을 받으세요.

빠른 시작

모든 요청은 Bearer 비밀 키로 인증됩니다. 테스트 모드로 시작하세요:

curl

# List specifications to find a spec_id
curl -G "https://partner.svoyager.com/v1/photo-specifications" \
  -H "Authorization: Bearer svoy_sk_test_YOUR_KEY" \
  --data-urlencode "country=US"

기본 URL 및 환경

모든 엔드포인트는 단일 기본 URL에서 제공됩니다:

Base URL

https://partner.svoyager.com/v1

환경 경로나 매개변수는 없습니다. 요청이 테스트 환경에서 실행되는지 라이브 환경에서 실행되는지는 전적으로 API 키 접두사(svoy_sk_test_… 대 svoy_sk_live_…)에 따라 결정됩니다. 응답에는 이를 livemode로 반환합니다.

인증

API 키

비밀 키가 포함된 Authorization 헤더를 사용하여 모든 요청을 인증하십시오. 키는 파트너 센터에서 생성 및 순환됩니다.

Header

Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx

접두사는 환경을 나타냅니다. 테스트 환경은 svoy_sk_test_…, 운영 환경은 svoy_sk_live_…입니다. 테스트 키는 운영 데이터에 대해 절대 작동할 수 없으며(반대의 경우도 마찬가지), 환경이 일치하지 않으면 401 wrong_environment 오류가 반환됩니다.

범위

키에는 명시적인 최소 권한 범위가 포함됩니다. 필수 범위가 누락된 요청은 403 insufficient_scope 오류를 반환합니다.

범위	권한 부여
photo.specs.read	List and retrieve photo specifications.
photo.sessions.read	Retrieve sessions and their previews.
photo.sessions.write	Create uploads and photo sessions (previews).
photo.finalize.write	Finalize a session into a no-watermark order.
photo.orders.read	Retrieve orders and download finals.

키 안전하게 보관하기

시크릿 키는 서버 간 통신에만 사용됩니다. 절대 브라우저나 모바일 코드, 공개 저장소, 클라이언트 측 번들에 시크릿 키를 포함하지 마십시오. 키가 유출된 경우, 파트너 센터에서 즉시 키를 교체하십시오.

핵심 API

엔드포인트

필수 입력란은 *로 표시되어 있습니다. 예시에는 실제 키가 아닌 자리 표시자 자격 증명이 사용됩니다.

POST/v1/uploads

Upload a photo

Create a short-lived presigned upload target, then PUT the raw image bytes straight to `upload_url`. This bypasses request-body size limits (product cap 10 MB). No quota is spent.

scope photo.sessions.write

요청

본문 (application/json)

필드	유형	설명
content_type*	string	MIME type of the image.`image/jpegimage/pngimage/webpimage/heic`

`upload_url` is single-use and expires; upload promptly and do not modify the URL.

요청 예시

curl

# 1) Create the upload target
curl -X POST "https://partner.svoyager.com/v1/uploads" \
  -H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"content_type":"image/jpeg"}'

# 2) PUT the bytes to the returned upload_url (exactly as returned)
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

응답 · 201

201 · application/json

{
  "object": "upload",
  "upload_url": "https://upload.svoyager.com/v1/EXAMPLE?signature=…",
  "upload_ref": "up_ref_tXk3W2b8Qe7Ra1Nc0",
  "max_bytes": 10485760,
  "expires_at": "2026-07-24T18: 20: 00Z"
}

오류

상태	코드	다음과 같은 경우
400	missing_content_type	`content_type` was not provided.
415	unsupported_format	The content type is not an accepted image format.
503	temporarily_unavailable	Uploads are temporarily unavailable.
502	upload_init_failed	The upload could not be initialised — retry shortly.

또한 표준 인증, 권한 및 속도 제한 오류도 포함됩니다 — 참조: 오류 및 재시도.

POST/v1/photo-sessions

Create a photo session

Generate a watermarked preview from an upload against a specification. Spends one `preview` unit of your plan. Review `issues` before finalizing.

scope photo.sessions.write Idempotency-Key 필수

요청

본문 (application/json)

필드	유형	설명
upload_ref*	string	The `upload_ref` from Upload a photo.
spec_id*	string	The `photo_specification` id (`spc_…`) to render against.

요청 예시

curl

curl -X POST "https://partner.svoyager.com/v1/photo-sessions" \
  -H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx" \
  -H "Idempotency-Key: a7f3c9e1-2b4d-4c8a-9f10-3e5d6b7a8c9d" \
  -H "Content-Type: application/json" \
  -d '{"upload_ref":"up_ref_tXk3W2b8Qe7Ra1Nc0","spec_id":"spc_9wTv2c1Kd8Qe"}'

응답 · 201

201 · application/json

{
  "object": "photo_session",
  "id": "3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10",
  "livemode": false,
  "status": "preview_ready",
  "spec_id": "spc_9wTv2c1Kd8Qe",
  "preview_url": "https://partner.svoyager.com/v1/photo-sessions/3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10/preview",
  "watermarked": true,
  "issues": [],
  "created_at": "2026-07-24T18: 30: 00Z"
}

오류

상태	코드	다음과 같은 경우
400	missing_idempotency_key	The `Idempotency-Key` header is missing.
400	missing_upload_ref	`upload_ref` is missing.
400	missing_spec_id	`spec_id` is missing.
400	invalid_upload_ref	The referenced upload could not be read.
413	file_too_large	The uploaded file exceeds 10 MB.
415	unsupported_format	The uploaded file is not an accepted image format.
404	spec_not_found	No active specification matches `spec_id`.
402	no_active_plan	No active plan is assigned for this environment.
402	quota_exceeded	Included preview quota for the period is exhausted.
402	plan_inactive	The plan is not active for this environment.
409	idempotency_key_reuse	The key was reused with a different body.
409	request_in_progress	A request with this key is still processing.
422	unprocessable_image	The image could not be processed.
502	provider_error	The preview could not be generated upstream — retry shortly.
503	provider_busy	The processing service is busy — retry shortly.

또한 표준 인증, 권한 및 속도 제한 오류도 포함됩니다 — 참조: 오류 및 재시도.

GET/v1/photo-sessions/{id}

Retrieve a photo session

Fetch a session by id, including its current status, `preview_url`, and any `issues`.

scope photo.sessions.read

요청

경로 매개변수

필드	유형	설명
id*	string	Session id.

요청 예시

curl

curl "https://partner.svoyager.com/v1/photo-sessions/3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10" \
  -H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx"

응답 · 200

200 · application/json

{
  "object": "photo_session",
  "id": "3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10",
  "livemode": false,
  "status": "preview_ready",
  "spec_id": "spc_9wTv2c1Kd8Qe",
  "preview_url": "https://partner.svoyager.com/v1/photo-sessions/3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10/preview",
  "watermarked": true,
  "issues": [],
  "created_at": "2026-07-24T18: 30: 00Z"
}

오류

상태	코드	다음과 같은 경우
404	session_not_found	No session matches the id for this account/environment.

또한 표준 인증, 권한 및 속도 제한 오류도 포함됩니다 — 참조: 오류 및 재시도.

GET/v1/photo-sessions/{id}/preview

Download the preview image

Stream the watermarked preview image bytes for a session (SVOYAGER-hosted; the upstream URL is never exposed). This is the resource `preview_url` points to.

scope photo.sessions.read이미지 바이트를 반환합니다.

요청

경로 매개변수

필드	유형	설명
id*	string	Session id.

Returns raw `image/*` bytes on success (not JSON).

요청 예시

curl

curl "https://partner.svoyager.com/v1/photo-sessions/3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10/preview" \
  -H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx" \
  --output preview.jpg

응답 · 200

성공 시 엔드포인트는 원시 이미지 바이트(JSON 아님)를 스트리밍합니다. 응답 본문을 파일에 저장하십시오.

오류

상태	코드	다음과 같은 경우
404	preview_not_found	The session or its preview does not exist.

또한 표준 인증, 권한 및 속도 제한 오류도 포함됩니다 — 참조: 오류 및 재시도.

POST/v1/photo-sessions/{id}/finalize

Finalize a photo

Turn a reviewed session into a deliverable order. In live mode this produces the no-watermark final and spends one `final` unit; in test mode it emulates the final from the preview.

scope photo.finalize.write Idempotency-Key 필수

요청

경로 매개변수

필드	유형	설명
id*	string	Session id to finalize.

요청 예시

curl

curl -X POST "https://partner.svoyager.com/v1/photo-sessions/3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10/finalize" \
  -H "Authorization: Bearer svoy_sk_live_A8m4Qz1YOURKEYHERExxxxxxx" \
  -H "Idempotency-Key: a7f3c9e1-2b4d-4c8a-9f10-3e5d6b7a8c9d"

응답 · 201Returns 200 with the existing order if the session was already finalized (never double-charged).

201 · application/json

{
  "object": "photo_order",
  "id": "8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284",
  "livemode": true,
  "sandbox_emulated": false,
  "status": "final_ready",
  "session_id": "3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10",
  "spec_id": "spc_9wTv2c1Kd8Qe",
  "final_url": "https://partner.svoyager.com/v1/orders/8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284/final",
  "watermarked": false,
  "created_at": "2026-07-24T18: 31: 00Z"
}

오류

상태	코드	다음과 같은 경우
400	missing_idempotency_key	The `Idempotency-Key` header is missing.
404	session_not_found	No session matches the id for this account/environment.
422	session_not_finalizable	The session is not in a finalizable state.
402	no_active_plan	No active plan is assigned for this environment.
402	quota_exceeded	Included final quota for the period is exhausted.
402	plan_inactive	The plan is not active for this environment.
409	idempotency_key_reuse	The key was reused with a different request.
409	request_in_progress	A request with this key is still processing.
502	provider_error	The final could not be produced upstream — retry shortly.
503	provider_busy	The processing service is busy — retry shortly.

또한 표준 인증, 권한 및 속도 제한 오류도 포함됩니다 — 참조: 오류 및 재시도.

GET/v1/orders/{id}

Retrieve an order

Fetch a finalized order by id, including its status and `final_url` once ready.

scope photo.orders.read

요청

경로 매개변수

필드	유형	설명
id*	string	Order id.

요청 예시

curl

curl "https://partner.svoyager.com/v1/orders/8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284" \
  -H "Authorization: Bearer svoy_sk_live_A8m4Qz1YOURKEYHERExxxxxxx"

응답 · 200

200 · application/json

{
  "object": "photo_order",
  "id": "8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284",
  "livemode": true,
  "sandbox_emulated": false,
  "status": "final_ready",
  "session_id": "3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10",
  "spec_id": "spc_9wTv2c1Kd8Qe",
  "final_url": "https://partner.svoyager.com/v1/orders/8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284/final",
  "watermarked": false,
  "created_at": "2026-07-24T18: 31: 00Z"
}

오류

상태	코드	다음과 같은 경우
404	order_not_found	No order matches the id for this account/environment.

또한 표준 인증, 권한 및 속도 제한 오류도 포함됩니다 — 참조: 오류 및 재시도.

GET/v1/orders/{id}/final

Download the final image

Stream the final image bytes for an order (SVOYAGER-hosted). In live mode this is the no-watermark deliverable; in test mode it is the sandbox-emulated copy. This is the resource `final_url` points to.

scope photo.orders.read이미지 바이트를 반환합니다.

요청

경로 매개변수

필드	유형	설명
id*	string	Order id.

Returns raw `image/*` bytes on success (not JSON).

요청 예시

curl

curl "https://partner.svoyager.com/v1/orders/8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284/final" \
  -H "Authorization: Bearer svoy_sk_live_A8m4Qz1YOURKEYHERExxxxxxx" \
  --output final.jpg

응답 · 200

성공 시 엔드포인트는 원시 이미지 바이트(JSON 아님)를 스트리밍합니다. 응답 본문을 파일에 저장하십시오.

오류

상태	코드	다음과 같은 경우
404	final_not_found	The order or its final does not exist.

또한 표준 인증, 권한 및 속도 제한 오류도 포함됩니다 — 참조: 오류 및 재시도.

GET/v1/photo-specifications

List photo specifications

Return a cursor-paginated list of available photo specifications. Filter by country or document type to find the `spec_id` you need.

scope photo.specs.read

요청

쿼리 매개변수

필드	유형	설명
limit	integer	Page size, 1–100 (default 20).
starting_after	string	A specification id (`spc_…`) to page after.
country	string	ISO-3166 alpha-2 filter, e.g. `US`.
document_type	string	Filter by document type, e.g. `passport`.

요청 예시

curl

curl -G "https://partner.svoyager.com/v1/photo-specifications" \
  -H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx" \
  --data-urlencode "country=US" \
  --data-urlencode "limit=20"

응답 · 200

200 · application/json

{
  "object": "list",
  "data": [
    {
      "object": "photo_specification",
      "id": "spc_9wTv2c1Kd8Qe",
      "name": "United States Passport"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

오류

이 엔드포인트는 아래의 표준 오류만 반환합니다.

또한 표준 인증, 권한 및 속도 제한 오류도 포함됩니다 — 참조: 오류 및 재시도.

GET/v1/photo-specifications/{id}

Retrieve a photo specification

Fetch a single specification by its stable `spec_id`, including its full requirements.

scope photo.specs.read

요청

경로 매개변수

필드	유형	설명
id*	string	Specification id (`spc_…`).

요청 예시

curl

curl "https://partner.svoyager.com/v1/photo-specifications/spc_9wTv2c1Kd8Qe" \
  -H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx"

응답 · 200

200 · application/json

{
  "object": "photo_specification",
  "id": "spc_9wTv2c1Kd8Qe",
  "name": "United States Passport",
  "country_code": "US",
  "document_type": "passport",
  "physical_size": {
    "width": 51,
    "height": 51,
    "unit": "mm"
  },
  "pixel_size": {
    "width": 600,
    "height": 600
  },
  "dpi": 300,
  "background": {
    "color": "#FFFFFF",
    "name": "white"
  },
  "requirements": {
    "head_height": "25–35 mm (1–1⅜ in)",
    "eye_to_bottom": "28–35 mm (1⅛–1⅜ in)",
    "recency_months": 6,
    "expression": "neutral",
    "color": true,
    "glasses": "not allowed",
    "eyes_and_ears": "both eyes open"
  },
  "updated_at": "2026-07-01T12: 00: 00Z"
}

오류

상태	코드	다음과 같은 경우
404	spec_not_found	No active specification matches the id.

또한 표준 인증, 권한 및 속도 제한 오류도 포함됩니다 — 참조: 오류 및 재시도.

이멱포텐시 및 안전한 재시도

재시도된 요청이 중복 청구되거나 중복 처리되지 않도록 Idempotency-Key 헤더(고유한 값, 예: UUID)를 전송하십시오. 다음의 경우 필수입니다:

POST /v1/photo-sessions
POST /v1/photo-sessions/{id}/finalize

• 동일한 키 + 동일한 본문 → 원래 결과가 재재생됩니다(추가 과금 없음, 재렌더링 없음).
• 동일한 키 + 다른 본문 → 409 idempotency_key_reuse.
• 재시도 가능한 오류의 경우, 동일한 키, 본문 및 upload_ref를 사용하여 재시도할 수 있습니다.
• 단일 세션에 대한 동시 최종 처리 요청은 두 건의 주문을 생성하거나 청구할 수 없습니다.

세션 및 주문 수명 주기

세션은 미리보기 상태를 거치며, 주문은 확정 상태를 거칩니다.

세션 상태

preview_ready — 미리보기 생성 완료, 문제 없음.
preview_has_issues — 이슈를 포함하여 생성된 미리보기.
preview_failed — 미리보기를 생성할 수 없습니다.
finalized — 세션이 종료되었습니다.

주문 상태

final_ready — 최종 버전이 제공됩니다.
processing — 최종본은 준비 중입니다.
failed — 최종화 실패.

테스트 환경 대 실제 운영 환경

환경은 키 접두사에 따라 결정되며, 클라이언트는 이를 전달할 수 없습니다. 테스트 모드에서는 실제 워터마크가 포함된 미리보기를 실행하여 실제 흐름을 연습할 수 있도록 하지만, 최종 결과를 에뮬레이트하므로 실제 할당량이나 프로덕션 렌더링은 사용되지 않습니다.

Aspect	테스트	실시간
livemode	false	true
미리 보기	실제, 워터마크 처리됨	실제, 워터마크 처리됨
최종	미리보기 버전에서 샌드박스 모드로 에뮬레이션됨	실제 이미지, 워터마크 없음
sandbox_emulated	true	false
watermarked	true	false
사용된 할당량	테스트 할당량만	실시간 할당량에만 적용

할당량 및 사용량

귀하의 요금제에는 기간별로 별도로 계산되는 일정 수의 미리보기 및 최종 승인 횟수가 포함되어 있습니다. 세션을 생성하면 미리보기 1회가 소모되며, 최종 승인을 완료하면 최종 승인 1회가 소모됩니다. 할당량은 처리 전에 원자적으로 예약됩니다.

포함된 미리보기 또는 최종 할당량이 소진되면, 요청은 402 quota_exceeded를 반환합니다.
402는 강제 중지 상태입니다. 다음 기간이 시작되거나 요금제가 변경될 때까지 재시도해도 성공하지 못합니다.
테스트 및 운영 할당량은 완전히 독립적입니다.

오류 및 재시도

모든 오류는 하나의 엔벨로프를 사용합니다. request_id는 X-Request-Id 응답 헤더에도 표시되므로, 지원 요청 시 이를 포함시켜 주십시오.

Error envelope

{
  "error": {
    "type": "invalid_request_error",
    "code": "quota_exceeded",
    "message": "Your included final quota for this period is exhausted.",
    "request_id": "req_9wTv2c1Kd8QeR7"
  }
}

표준 오류 (모든 엔드포인트)

상태	코드	다음과 같은 경우
401	invalid_api_key	Missing, malformed, or unknown API key.
401	revoked_api_key	The key was revoked.
401	expired_api_key	The key passed its rotation grace period.
401	wrong_environment	A test key was used on live traffic (or vice versa).
403	client_disabled	The API client is disabled.
403	api_access_revoked	API access for the account is not active.
403	insufficient_scope	The key lacks the required scope for this endpoint.
429	rate_limited	Per-key rate limit exceeded. Honour `Retry-After`.

422는 확인된 이미지 문제인 경우에만 반환됩니다. 402는 할당량이 소진되었음을 의미합니다. 409는 이멱포텐시 또는 리소스 충돌을 나타냅니다.

429는 키별 요청 제한에 도달했음을 의미합니다. Retry-After 헤더를 준수하십시오. 502/503 및 기타 5xx 오류의 경우, 백오프(backoff)를 적용하고 동일한 Idempotency-Key를 사용하여 재시도하십시오.

사진 문제 코드

미리보기 결과에는 0개 이상의 문제가 반환될 수 있으며, 각 문제는 안정적인 코드 + 메시지로 구성됩니다. 최종 사용자가 사진을 다시 촬영할 수 있도록 이러한 정보를 표시하십시오. 인식되지 않은 업스트림 신호는 'other'로 처리됩니다.

코드	메시지
face_not_found	No face was detected in the photo.
uneven_lighting	Lighting on the face is uneven.
poor_brightness	Face brightness is too dark, too bright, or the photo is low quality.
low_sharpness	The photo is blurry or not sharp enough.
eyeglasses_not_allowed	Eyeglasses are not allowed.
sunglasses_not_allowed	Sunglasses are not allowed.
headwear_not_allowed	Hats or head coverings are not allowed.
face_mask_not_allowed	A face mask is not allowed.
face_covering_found	A face covering was detected.
expression_not_neutral	The expression is not neutral.
crop_bottom	Not enough space is visible below the shoulders.
crop_left	Not enough of the left shoulder is visible.
crop_right	Not enough of the right shoulder is visible.
head_turned	The head is turned too far to the side.
head_tilted	The head is tilted too far up or down.
not_in_color	The photo must be in color.
other	The photo did not meet a requirement.

파일, 보존 기간 및 개인정보 보호

• 미리보기 및 최종 버전은 SVOYAGER에서 호스팅하고 인증된 URL을 통해서만 제공됩니다. 액세스하려면 API 키와 올바른 범위가 필요하며, 기본 저장소는 절대 공개되지 않습니다.
• 업로드된 이미지는 비공개이며 귀하의 계정과 환경으로 범위가 제한됩니다. 업로드 대상은 수명이 짧고 일회용입니다.
• 문서 내 사진은 결과물을 생성하기 위해 처리되며, 계정 간에 공유되지 않습니다.

SVOYAGER의 데이터 처리, 보존 및 삭제 약관을 참조하십시오:개인정보 처리방침 ·파트너 계약 및 약관

SVOYAGER ID Photo API

개요

기능 설명

미리 보기 → 최종 워크플로우

빠른 시작

기본 URL 및 환경

인증

API 키

범위

키 안전하게 보관하기

엔드포인트

Upload a photo

Create a photo session

Retrieve a photo session

Download the preview image

Finalize a photo

Retrieve an order

Download the final image

List photo specifications

Retrieve a photo specification

이멱포텐시 및 안전한 재시도

세션 및 주문 수명 주기

테스트 환경 대 실제 운영 환경

할당량 및 사용량

오류 및 재시도

사진 문제 코드

파일, 보존 기간 및 개인정보 보호