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

Ошибки

Статус	Код	Когда
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 — Ошибка финализации.

Тестовая среда и производственная среда

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

Аспект	Тест	В режиме реального времени
livemode	false	true
Предварительный просмотр	Подлинный, с водяным знаком	Подлинный, с водяным знаком
Окончательный вариант	Эмулируется в Sandbox на основе предварительной версии	Настоящее изображение, без водяных знаков
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.

Коды проблем с фотографиями

Предварительный просмотр может вернуть ноль или более проблем, каждая из которых представляет собой стабильный код + сообщение. Отобразите их конечному пользователю, чтобы он мог повторно сделать фотографию. Нераспознанный сигнал из вышестоящего уровня преобразуется в «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.

Файлы, срок хранения и конфиденциальность

• Предварительные и окончательные версии предоставляются только с авторизованных 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

Идемпотентность и безопасные повторные попытки

Жизненный цикл сеанса и заказа

Тестовая среда и производственная среда

Квоты и использование

Ошибки и повторные попытки

Коды проблем с фотографиями

Файлы, срок хранения и конфиденциальность