ID PhotoREST · JSONOpenAPI 3.1

SVOYAGER ID Photo API

あらゆる写真を、規定に準拠したID写真・パスポート写真・ビザ用写真に変換します。

概要

機能の説明

SVOYAGERのID Photo APIは、通常のポートレート写真を規格に準拠した証明写真に変換します。ID Photoは単一の製品であり、パスポート、ビザ、居住許可証、国民IDは、個別の製品ではなく、証明書類の仕様として扱われます。写真をアップロードし、仕様に基づいて透かし入りのプレビューを生成した後、確定処理を行って透かしのない結果を取得します。

プレビュー → 最終ワークフロー

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

エラー

ステータス	コード	When
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"
}

エラー

ステータス	コード	When
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"
}

エラー

ステータス	コード	When
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ではない）をストリームで返します。レスポンス本文をファイルに保存してください。

エラー

ステータス	コード	When
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"
}

エラー

ステータス	コード	When
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"
}

エラー

ステータス	コード	When
404	order_not_found	No order matches the id for this account/environment.

さらに、標準的な認証、権限、レート制限に関するエラーも含まれます — 詳細はエラーと再試行.

GET/v1/orders/{id}/final

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ではない）をストリームで返します。レスポンス本文をファイルに保存してください。

エラー

ステータス	コード	When
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"
}

エラー

ステータス	コード	When
404	spec_not_found	No active specification matches the id.

さらに、標準的な認証、権限、レート制限に関するエラーも含まれます — 詳細はエラーと再試行.

冪等性および安全な再試行

再試行されたリクエストで二重課金や二重処理が発生しないよう、Idempotency-Keyヘッダー（一意の値、例：UUID）を送信してください。これは以下の場合に必須です：

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

• 同じキー + 同じボディ → 元の結果が再再生されます（2回目の課金や2回目のレンダリングは発生しません）。
• 同じキー＋異なるボディ → 409 idempotency_key_reuse。
• 再試行可能なエラーの場合、同じキー、ボディ、および upload_ref を使用して再試行できます。
• 1つのセッションにおける同時処理中のリクエストの完了によって、2つの注文が作成されたり課金されたりすることは決してありません。

セッションおよび注文のライフサイクル

セッションはプレビュー状態を順次通過し、注文は確定状態を順次通過します。

セッションステータス

preview_ready — プレビューが生成されました。問題はありません。
preview_has_issues — 課題に基づいて生成されたプレビュー。
preview_failed — プレビューを生成できませんでした。
finalized — セッションが終了しました。

注文状況

final_ready — 最終版が利用可能です。
processing — 最終版は現在準備中です。
failed — 確定に失敗しました。

テスト環境と本番環境

環境はキーのプレフィックスによって決定されます。クライアントがこれを渡すことは決してありません。テストモードでは、実際の透かし入りプレビューが実行されるため、実際のフローを検証できますが、最終的な処理をエミュレートするため、本番環境のクォータや本番レンダリングは使用されません。

アスペクト	テスト	ライブ
livemode	false	true
プレビュー	実データ、透かし入り	実データ、透かし入り
最終版	プレビュー版からサンドボックスでエミュレート	本物、透かしなし
sandbox_emulated	true	false
watermarked	true	false
消費されたクォータ	クォータのテストのみ	ライブクォータのみ

クォータと使用状況

ご契約プランには、期間ごとにプレビューとファイナルの各割り当て数が含まれており、これらは別々にカウントされます。セッションの作成にはプレビューが1回、確定にはファイナルが1回消費されます。割り当ては処理前にアトミックに予約されます。

含まれるプレビューまたは最終クォータが使い切られた場合、リクエストは 402 quota_exceeded を返します。
402は完全な停止状態です。次の期間が始まるか、プランが変更されるまで、再試行しても成功しません。
テスト環境と本番環境のクォータは完全に独立しています。

エラーと再試行

エラーごとに1つのエンベロープが使用されます。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"
  }
}

標準エラー（すべてのエンドポイント）

ステータス	コード	When
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を使用して再試行してください。

写真の問題コード

プレビューでは、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キーと正しいスコープが必要です。基盤となるストレージが一般に公開されることは決してありません。
• アップロードされた画像は非公開であり、アカウントおよび環境に限定されます。アップロード先の一時的なリソースは短期間しか存続せず、1回限りの使用となります。
• ドキュメントの写真は、結果を生成するために処理されるものであり、アカウント間で共有されることはありません。

SVOYAGERのデータ処理、保存、および削除に関する規約を参照してください：プライバシーポリシー ·パートナー契約および利用規約