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, що містить ваш секретний ключ. Ключі створюються та оновлюються в Partner Center.

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

Помилки

Статус	Код	Коли
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 — попередній перегляд, згенерований із використанням issues.
preview_failed — Попередній перегляд не вдалося створити.
finalized — сесія була завершена.

Статус замовлення

final_ready — Остаточний варіант доступний.
processing — Остаточний варіант готується.
failed — Фіналізація не вдалася.

Тестове середовище та виробниче середовище

Середовище визначається префіксом вашого ключа — клієнти ніколи не можуть його передавати. У тестовому режимі відображається реальний попередній перегляд із водяним знаком, щоб ви могли відпрацювати реальний робочий процес, але він імітує кінцевий результат, тому не використовуються реальні квоти чи рендеринг у виробничому середовищі.

Аспект	Тест	Live
livemode	false	true
Попередній перегляд	Справжній, з водяним знаком	Справжній, з водяним знаком
Остаточний варіант	Емульовано в пісочниці на основі попереднього перегляду	Справжнє зображення, без водяних знаків
sandbox_emulated	true	false
watermarked	true	false
Використана квота	Тільки для тестової квоти	Тільки для квоти в режимі реального часу

Квоти та використання

Ваш тарифний план передбачає певну кількість попередніх переглядів та остаточних переглядів за період, які підраховуються окремо. Створення сесії витрачає один попередній перегляд; фіналізація — один остаточний перегляд. Квота резервується атомарно перед обробкою.

Коли включений попередній перегляд або остаточна квота вичерпані, запит повертає код 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 повторіть спробу з затримкою та тим самим Idempotency-Key.

Коди проблем із фотографіями

Попередній перегляд може повернути нуль або більше проблем, кожна з яких складається зі стабільного коду та повідомлення. Покажіть їх кінцевому користувачеві, щоб він міг повторно зробити фото. Нерозпізнаний сигнал від джерела погіршується до категорії «інше».

Код	Повідомлення
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.

Файли, термін зберігання та конфіденційність

• Попередні та остаточні версії надаються виключно з аутентифікованих URL-адрес, розміщених на хостингу SVOYAGER. Для доступу необхідний ваш ключ 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

Ідемпотентність та безпечні повторні спроби

Життєвий цикл сеансу та замовлення

Тестове середовище та виробниче середовище

Квоти та використання

Помилки та повторні спроби

Коди проблем із фотографіями

Файли, термін зберігання та конфіденційність