ID PhotoREST · JSONOpenAPI 3.1

SVOYAGER ID Photo API

Herhangi bir fotoğrafı, kurallara uygun bir kimlik / pasaport / vize fotoğrafına dönüştürün.

Genel Bakış

Ne işe yarar?

SVOYAGER ID Photo API, sıradan bir portreyi standartlara uygun bir belge fotoğrafına dönüştürür. ID Photo tek bir üründür: pasaport, vize, oturma izni ve ulusal kimlik, ayrı ürünler olarak değil, belge spesifikasyonları olarak temsil edilir. Bir fotoğraf yükler, bir spesifikasyona göre filigranlı bir önizleme oluşturur, ardından sonlandırma işlemini gerçekleştirerek filigransız sonucu elde edersiniz.

Önizleme → nihai iş akışı

  1. 1Bir fotoğraf yükleyin. Bir yükleme hedefi oluşturun ve görüntü baytlarını bu hedefe gönderin.
  2. 2Bir oturum oluşturun. Bir spesifikasyona göre filigranlı bir önizleme oluşturun. Geri dönen sorunları inceleyin.
  3. 3Sonlandır. İncelenen oturumu bir siparişe dönüştürün ve filigran içermeyen nihai dosyayı alın.

Hızlı Başlangıç

Her istek, bir Bearer gizli anahtarı ile doğrulanır. Test modunda başlayın:

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"

Temel URL ve ortamlar

Tüm uç noktalar tek bir temel URL altında sunulur:

Base URL
https://partner.svoyager.com/v1

Ortam yolu veya parametresi yoktur. Bir isteğin test ortamında mı yoksa canlı ortamda mı çalışacağı tamamen API anahtar ön ekinize göre belirlenir (svoy_sk_test_… ile svoy_sk_live_… arasındaki fark). Yanıtlar bunu livemode olarak yansıtır.

Kimlik Doğrulama

API anahtarları

Her isteği, gizli anahtarınızı içeren bir Authorization başlığıyla doğrulayın. Anahtarlar, İş Ortağı Merkezi'nde oluşturulur ve değiştirilir.

Header
Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx

Önek, ortamı belirler: test için svoy_sk_test_…, canlı ortam için svoy_sk_live_…. Bir test anahtarı asla canlı veriler üzerinde işlem yapamaz (ve bunun tersi de geçerlidir) — uyuşmazlıklar 401 wrong_environment hatasını döndürür.

Kapsamlar

Anahtarlar, açıkça belirtilen en düşük ayrıcalıklı kapsamlara sahiptir. Gerekli kapsamın eksik olduğu bir istek, 403 insufficient_scope hatası ile yanıtlanır.

KapsamYetki Verileri
photo.specs.readList and retrieve photo specifications.
photo.sessions.readRetrieve sessions and their previews.
photo.sessions.writeCreate uploads and photo sessions (previews).
photo.finalize.writeFinalize a session into a no-watermark order.
photo.orders.readRetrieve orders and download finals.

Anahtarları güvende tutma

Gizli anahtarlar yalnızca sunucu-sunucu iletişimi içindir. Gizli bir anahtarı asla tarayıcı veya mobil koduna, halka açık bir depoya ya da istemci tarafı paketine eklemeyin. Bir anahtarın ifşa olması durumunda, Partner Center'da derhal değiştirin.

Temel API

Uç Noktalar

Zorunlu alanlar * ile işaretlenmiştir. Örneklerde yer tutucu kimlik bilgileri kullanılır — asla gerçek anahtarlar kullanılmaz.

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.

kapsam photo.sessions.write
İstek
Gövde (application/json)
AlanTürAçıklama
content_type*stringMIME type of the image.image/jpegimage/pngimage/webpimage/heic
  • `upload_url` is single-use and expires; upload promptly and do not modify the URL.
Örnek istek
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
Yanıt · 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"
}
Hatalar
DurumKodNe zaman
400missing_content_type`content_type` was not provided.
415unsupported_formatThe content type is not an accepted image format.
503temporarily_unavailableUploads are temporarily unavailable.
502upload_init_failedThe upload could not be initialised — retry shortly.

Ayrıca standart kimlik doğrulama, izin ve hız sınırı hataları — bkz. Hatalar ve yeniden denemeler.

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.

kapsam photo.sessions.write Idempotency-Key zorunludur
İstek
Gövde (application/json)
AlanTürAçıklama
upload_ref*stringThe `upload_ref` from Upload a photo.
spec_id*stringThe `photo_specification` id (`spc_…`) to render against.
Örnek istek
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"}'
Yanıt · 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"
}
Hatalar
DurumKodNe zaman
400missing_idempotency_keyThe `Idempotency-Key` header is missing.
400missing_upload_ref`upload_ref` is missing.
400missing_spec_id`spec_id` is missing.
400invalid_upload_refThe referenced upload could not be read.
413file_too_largeThe uploaded file exceeds 10 MB.
415unsupported_formatThe uploaded file is not an accepted image format.
404spec_not_foundNo active specification matches `spec_id`.
402no_active_planNo active plan is assigned for this environment.
402quota_exceededIncluded preview quota for the period is exhausted.
402plan_inactiveThe plan is not active for this environment.
409idempotency_key_reuseThe key was reused with a different body.
409request_in_progressA request with this key is still processing.
422unprocessable_imageThe image could not be processed.
502provider_errorThe preview could not be generated upstream — retry shortly.
503provider_busyThe processing service is busy — retry shortly.

Ayrıca standart kimlik doğrulama, izin ve hız sınırı hataları — bkz. Hatalar ve yeniden denemeler.

GET/v1/photo-sessions/{id}

Retrieve a photo session

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

kapsam photo.sessions.read
İstek
Yol parametreleri
AlanTürAçıklama
id*stringSession id.
Örnek istek
curl
curl "https://partner.svoyager.com/v1/photo-sessions/3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10" \
  -H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx"
Yanıt · 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"
}
Hatalar
DurumKodNe zaman
404session_not_foundNo session matches the id for this account/environment.

Ayrıca standart kimlik doğrulama, izin ve hız sınırı hataları — bkz. Hatalar ve yeniden denemeler.

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.

kapsam photo.sessions.readGörüntü baytlarını döndürür
İstek
Yol parametreleri
AlanTürAçıklama
id*stringSession id.
  • Returns raw `image/*` bytes on success (not JSON).
Örnek istek
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
Yanıt · 200

İşlem başarılı olursa, uç nokta ham görüntü baytlarını (JSON değil) aktarır. Yanıt gövdesini bir dosyaya kaydedin.

Hatalar
DurumKodNe zaman
404preview_not_foundThe session or its preview does not exist.

Ayrıca standart kimlik doğrulama, izin ve hız sınırı hataları — bkz. Hatalar ve yeniden denemeler.

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.

kapsam photo.finalize.write Idempotency-Key zorunludur
İstek
Yol parametreleri
AlanTürAçıklama
id*stringSession id to finalize.
Örnek istek
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"
Yanıt · 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"
}
Hatalar
DurumKodNe zaman
400missing_idempotency_keyThe `Idempotency-Key` header is missing.
404session_not_foundNo session matches the id for this account/environment.
422session_not_finalizableThe session is not in a finalizable state.
402no_active_planNo active plan is assigned for this environment.
402quota_exceededIncluded final quota for the period is exhausted.
402plan_inactiveThe plan is not active for this environment.
409idempotency_key_reuseThe key was reused with a different request.
409request_in_progressA request with this key is still processing.
502provider_errorThe final could not be produced upstream — retry shortly.
503provider_busyThe processing service is busy — retry shortly.

Ayrıca standart kimlik doğrulama, izin ve hız sınırı hataları — bkz. Hatalar ve yeniden denemeler.

GET/v1/orders/{id}

Retrieve an order

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

kapsam photo.orders.read
İstek
Yol parametreleri
AlanTürAçıklama
id*stringOrder id.
Örnek istek
curl
curl "https://partner.svoyager.com/v1/orders/8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284" \
  -H "Authorization: Bearer svoy_sk_live_A8m4Qz1YOURKEYHERExxxxxxx"
Yanıt · 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"
}
Hatalar
DurumKodNe zaman
404order_not_foundNo order matches the id for this account/environment.

Ayrıca standart kimlik doğrulama, izin ve hız sınırı hataları — bkz. Hatalar ve yeniden denemeler.

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.

kapsam photo.orders.readGörüntü baytlarını döndürür
İstek
Yol parametreleri
AlanTürAçıklama
id*stringOrder id.
  • Returns raw `image/*` bytes on success (not JSON).
Örnek istek
curl
curl "https://partner.svoyager.com/v1/orders/8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284/final" \
  -H "Authorization: Bearer svoy_sk_live_A8m4Qz1YOURKEYHERExxxxxxx" \
  --output final.jpg
Yanıt · 200

İşlem başarılı olursa, uç nokta ham görüntü baytlarını (JSON değil) aktarır. Yanıt gövdesini bir dosyaya kaydedin.

Hatalar
DurumKodNe zaman
404final_not_foundThe order or its final does not exist.

Ayrıca standart kimlik doğrulama, izin ve hız sınırı hataları — bkz. Hatalar ve yeniden denemeler.

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.

kapsam photo.specs.read
İstek
Sorgu parametreleri
AlanTürAçıklama
limitintegerPage size, 1–100 (default 20).
starting_afterstringA specification id (`spc_…`) to page after.
countrystringISO-3166 alpha-2 filter, e.g. `US`.
document_typestringFilter by document type, e.g. `passport`.
Örnek istek
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"
Yanıt · 200
200 · application/json
{
  "object": "list",
  "data": [
    {
      "object": "photo_specification",
      "id": "spc_9wTv2c1Kd8Qe",
      "name": "United States Passport"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
Hatalar

Bu uç nokta yalnızca aşağıdaki standart hataları döndürür.

Ayrıca standart kimlik doğrulama, izin ve hız sınırı hataları — bkz. Hatalar ve yeniden denemeler.

GET/v1/photo-specifications/{id}

Retrieve a photo specification

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

kapsam photo.specs.read
İstek
Yol parametreleri
AlanTürAçıklama
id*stringSpecification id (`spc_…`).
Örnek istek
curl
curl "https://partner.svoyager.com/v1/photo-specifications/spc_9wTv2c1Kd8Qe" \
  -H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx"
Yanıt · 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"
}
Hatalar
DurumKodNe zaman
404spec_not_foundNo active specification matches the id.

Ayrıca standart kimlik doğrulama, izin ve hız sınırı hataları — bkz. Hatalar ve yeniden denemeler.

Yeniden denenen bir isteğin asla iki kez ücretlendirilmemesi veya iki kez işlenmemesi için bir Idempotency-Key başlığı (benzersiz bir değer, ör. bir UUID) gönderin. Bu, aşağıdaki durumlarda zorunludur:

  • POST /v1/photo-sessions
  • POST /v1/photo-sessions/{id}/finalize
  • Aynı anahtar + aynı gövde → orijinal sonuç yeniden oynatılır (ikinci bir ücretlendirme veya ikinci bir görüntüleme olmaz).
  • Aynı anahtar + farklı gövde → 409 idempotency_key_reuse.
  • Tekrar deneme yapılabilen bir hata, aynı anahtar, gövde ve upload_ref ile yeniden deneme yapmanıza olanak tanır.
  • Bir oturum için eşzamanlı olarak sonlandırılan istekler, asla iki sipariş oluşturmaz veya ücretlendirme yapmaz.

Bir oturum önizleme durumları arasında ilerler; bir sipariş ise sonlandırma durumları arasında ilerler.

Oturum durumu
  • preview_readyÖnizleme oluşturuldu, herhangi bir sorun yok.
  • preview_has_issuessorunlarla oluşturulan önizleme.
  • preview_failedÖnizleme oluşturulamadı.
  • finalizedoturum sonlandırıldı.
Sipariş durumu
  • final_readySon hali mevcuttur.
  • processingSon hali hazırlanmaktadır.
  • failedsonlandırma başarısız oldu.

Ortam, anahtar önekiniz tarafından belirlenir — istemciler bunu asla iletemez. Test modu, gerçek akışı deneyimlemeniz için filigranlı gerçek önizlemeyi çalıştırır, ancak nihai sonucu simüle eder; bu nedenle canlı kota veya üretim renderı kullanılmaz.

AspectTestCanlı
livemodefalsetrue
ÖnizlemeGerçek, filigranlıGerçek, filigranlı
SonÖnizlemeden sanal ortamda simüle edilmiştirGerçek, filigran yok
sandbox_emulatedtruefalse
watermarkedtruefalse
Kullanılan kotaYalnızca kota testiYalnızca canlı kota

Planınız, dönem başına ayrı ayrı sayılan bir dizi önizleme ve son hal hakkı içerir. Bir oturum oluşturmak bir önizleme hakkını, son hal işlemek ise bir son hal hakkını tüketir. Kota, işleme öncesinde atomik olarak ayrılır.

  • Dahil edilen önizleme veya nihai kota tükendiğinde, istek 402 quota_exceeded hatası döndürür.
  • 402, kesin bir durdurmadır — bir sonraki döneme veya plan değişikliğine kadar yeniden deneme başarılı olmaz.
  • Test ve canlı kotalar tamamen bağımsızdır.

Her hata bir zarf kullanır. Request_id, X-Request-Id yanıt başlığında da görünür — destek taleplerine bunu ekleyin.

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

Standart hatalar (tüm uç noktalar)

DurumKodNe zaman
401invalid_api_keyMissing, malformed, or unknown API key.
401revoked_api_keyThe key was revoked.
401expired_api_keyThe key passed its rotation grace period.
401wrong_environmentA test key was used on live traffic (or vice versa).
403client_disabledThe API client is disabled.
403api_access_revokedAPI access for the account is not active.
403insufficient_scopeThe key lacks the required scope for this endpoint.
429rate_limitedPer-key rate limit exceeded. Honour `Retry-After`.

422 kodu yalnızca doğrulanmış bir görüntü sorunu için döndürülür. 402, kota sınırının aşıldığı anlamına gelir. 409 ise idempotans veya kaynak çakışması anlamına gelir.

429 kodu, anahtar başına hız sınırına ulaştığınız anlamına gelir — Retry-After başlığını dikkate alın. 502/503 ve diğer 5xx hataları için, bekleme süresi uygulayarak ve aynı Idempotency-Key ile yeniden deneyin.

Bir önizleme, her biri bir kararlı kod + mesajdan oluşan sıfır veya daha fazla sorun döndürebilir. Son kullanıcının fotoğrafı yeniden çekebilmesi için bunları son kullanıcıya gösterin. Tanınmayan bir yukarı akış sinyali, "other" durumuna düşürülür.

KodMesaj
face_not_foundNo face was detected in the photo.
uneven_lightingLighting on the face is uneven.
poor_brightnessFace brightness is too dark, too bright, or the photo is low quality.
low_sharpnessThe photo is blurry or not sharp enough.
eyeglasses_not_allowedEyeglasses are not allowed.
sunglasses_not_allowedSunglasses are not allowed.
headwear_not_allowedHats or head coverings are not allowed.
face_mask_not_allowedA face mask is not allowed.
face_covering_foundA face covering was detected.
expression_not_neutralThe expression is not neutral.
crop_bottomNot enough space is visible below the shoulders.
crop_leftNot enough of the left shoulder is visible.
crop_rightNot enough of the right shoulder is visible.
head_turnedThe head is turned too far to the side.
head_tiltedThe head is tilted too far up or down.
not_in_colorThe photo must be in color.
otherThe photo did not meet a requirement.
  • Önizlemeler ve nihai sürümler yalnızca SVOYAGER tarafından barındırılan, kimlik doğrulaması yapılmış URL'lerden sunulur. Erişim için API anahtarınız ve doğru kapsam gereklidir — altta yatan depolama alanı hiçbir zaman kamuya açık hale getirilmez.
  • Yüklenen resimler özeldir ve hesabınızla ortamınızla sınırlıdır; yükleme hedefleri kısa ömürlüdür ve tek kullanımlıktır.
  • Sonucunuzu oluşturmak için belge fotoğrafları işlenir ve hesaplar arasında paylaşılmaz.

SVOYAGER’in veri işleme, saklama ve silme koşullarına bakın:Gizlilik Politikası ·Ortaklık Sözleşmesi ve Koşulları