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ışı
- 1Bir fotoğraf yükleyin. Bir yükleme hedefi oluşturun ve görüntü baytlarını bu hedefe gönderin.
- 2Bir oturum oluşturun. Bir spesifikasyona göre filigranlı bir önizleme oluşturun. Geri dönen sorunları inceleyin.
- 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:
# 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:
https://partner.svoyager.com/v1Ortam 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.
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.
| Kapsam | Yetki Verileri |
|---|---|
| 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. |
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.
Uç Noktalar
Zorunlu alanlar * ile işaretlenmiştir. Örneklerde yer tutucu kimlik bilgileri kullanılır — asla gerçek anahtarlar kullanılmaz.
/v1/uploadsUpload 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.
photo.sessions.write| Alan | Tür | Açıklama |
|---|---|---|
| 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.
# 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{
"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"
}| Durum | Kod | Ne zaman |
|---|---|---|
| 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. |
Ayrıca standart kimlik doğrulama, izin ve hız sınırı hataları — bkz. Hatalar ve yeniden denemeler.
/v1/photo-sessionsCreate a photo session
Generate a watermarked preview from an upload against a specification. Spends one `preview` unit of your plan. Review `issues` before finalizing.
photo.sessions.write Idempotency-Key zorunludur| Alan | Tür | Açıklama |
|---|---|---|
| upload_ref* | string | The `upload_ref` from Upload a photo. |
| spec_id* | string | The `photo_specification` id (`spc_…`) to render against. |
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"}'{
"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"
}| Durum | Kod | Ne zaman |
|---|---|---|
| 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. |
Ayrıca standart kimlik doğrulama, izin ve hız sınırı hataları — bkz. Hatalar ve yeniden denemeler.
/v1/photo-sessions/{id}Retrieve a photo session
Fetch a session by id, including its current status, `preview_url`, and any `issues`.
photo.sessions.read| Alan | Tür | Açıklama |
|---|---|---|
| id* | string | Session id. |
curl "https://partner.svoyager.com/v1/photo-sessions/3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10" \
-H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx"{
"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"
}| Durum | Kod | Ne zaman |
|---|---|---|
| 404 | session_not_found | No 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.
/v1/photo-sessions/{id}/previewDownload 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.
photo.sessions.readGörüntü baytlarını döndürür| Alan | Tür | Açıklama |
|---|---|---|
| id* | string | Session id. |
- Returns raw `image/*` bytes on success (not JSON).
curl "https://partner.svoyager.com/v1/photo-sessions/3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10/preview" \
-H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx" \
--output preview.jpgİş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.
| Durum | Kod | Ne zaman |
|---|---|---|
| 404 | preview_not_found | The 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.
/v1/photo-sessions/{id}/finalizeFinalize 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.
photo.finalize.write Idempotency-Key zorunludur| Alan | Tür | Açıklama |
|---|---|---|
| id* | string | Session id to finalize. |
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"{
"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"
}| Durum | Kod | Ne zaman |
|---|---|---|
| 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. |
Ayrıca standart kimlik doğrulama, izin ve hız sınırı hataları — bkz. Hatalar ve yeniden denemeler.
/v1/orders/{id}Retrieve an order
Fetch a finalized order by id, including its status and `final_url` once ready.
photo.orders.read| Alan | Tür | Açıklama |
|---|---|---|
| id* | string | Order id. |
curl "https://partner.svoyager.com/v1/orders/8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284" \
-H "Authorization: Bearer svoy_sk_live_A8m4Qz1YOURKEYHERExxxxxxx"{
"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"
}| Durum | Kod | Ne zaman |
|---|---|---|
| 404 | order_not_found | No 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.
/v1/orders/{id}/finalDownload 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.
photo.orders.readGörüntü baytlarını döndürür| Alan | Tür | Açıklama |
|---|---|---|
| id* | string | Order id. |
- Returns raw `image/*` bytes on success (not JSON).
curl "https://partner.svoyager.com/v1/orders/8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284/final" \
-H "Authorization: Bearer svoy_sk_live_A8m4Qz1YOURKEYHERExxxxxxx" \
--output final.jpgİş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.
| Durum | Kod | Ne zaman |
|---|---|---|
| 404 | final_not_found | The 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.
/v1/photo-specificationsList photo specifications
Return a cursor-paginated list of available photo specifications. Filter by country or document type to find the `spec_id` you need.
photo.specs.read| Alan | Tür | Açıklama |
|---|---|---|
| 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 -G "https://partner.svoyager.com/v1/photo-specifications" \
-H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx" \
--data-urlencode "country=US" \
--data-urlencode "limit=20"{
"object": "list",
"data": [
{
"object": "photo_specification",
"id": "spc_9wTv2c1Kd8Qe",
"name": "United States Passport"
}
],
"has_more": false,
"next_cursor": null
}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.
/v1/photo-specifications/{id}Retrieve a photo specification
Fetch a single specification by its stable `spec_id`, including its full requirements.
photo.specs.read| Alan | Tür | Açıklama |
|---|---|---|
| id* | string | Specification id (`spc_…`). |
curl "https://partner.svoyager.com/v1/photo-specifications/spc_9wTv2c1Kd8Qe" \
-H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx"{
"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"
}| Durum | Kod | Ne zaman |
|---|---|---|
| 404 | spec_not_found | No 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-sessionsPOST /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.
preview_ready— Önizleme oluşturuldu, herhangi bir sorun yok.preview_has_issues— sorunlarla oluşturulan önizleme.preview_failed— Önizleme oluşturulamadı.finalized— oturum sonlandırıldı.
final_ready— Son hali mevcuttur.processing— Son hali hazırlanmaktadır.failed— sonlandı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.
| Aspect | Test | Canlı |
|---|---|---|
| livemode | false | true |
| Önizleme | Gerçek, filigranlı | Gerçek, filigranlı |
| Son | Önizlemeden sanal ortamda simüle edilmiştir | Gerçek, filigran yok |
| sandbox_emulated | true | false |
| watermarked | true | false |
| Kullanılan kota | Yalnızca kota testi | Yalnı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": {
"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)
| Durum | Kod | Ne zaman |
|---|---|---|
| 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 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.
| Kod | Mesaj |
|---|---|
| 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. |
- • Ö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ı