ID PhotoREST · JSONOpenAPI 3.1

SVOYAGER ID Photo API

Omvandla valfritt foto till ett godkänt ID-, pass- eller visumfoto.

SVOYAGER ID Photo API förvandlar ett vanligt porträtt till ett godkänt dokumentfoto. ID Photo är en enda produkt: pass, visum, uppehållstillstånd och nationellt ID representeras som dokumentspecifikationer, inte som separata produkter. Du laddar upp ett foto, genererar en förhandsgranskning med vattenstämpel utifrån en specifikation och slutför sedan för att få resultatet utan vattenstämpel.

Förhandsgranskning → slutgiltigt arbetsflöde

1Ladda upp en bild. Skapa en uppladdningsdestination och skicka bildens byte till den.
2Skapa en session. Skapa en förhandsgranskning med vattenstämpel utifrån en specifikation. Granska de återgivna problemen.
3Slutför. Omvandla den granskade sessionen till en beställning och få den slutgiltiga versionen utan vattenstämpel.

Snabbstart

Varje förfrågan autentiseras med en hemlig Bearer-nyckel. Börja i testläge:

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"

Bas-URL och miljöer

Alla slutpunkter betjänas under en enda bas-URL:

Base URL

https://partner.svoyager.com/v1

Det finns ingen miljöväg eller parameter. Huruvida en begäran körs i test- eller live-läge avgörs helt och hållet av ditt API-nyckelprefix (svoy_sk_test_… jämfört med svoy_sk_live_…). Svaren återspeglar detta som livemode.

Autentisering

API-nycklar

Autentisera varje förfrågan med en Authorization-rubrik som innehåller din hemliga nyckel. Nycklar skapas och byts ut i Partner Center.

Header

Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx

Prefixet anger miljön: svoy_sk_test_… för test, svoy_sk_live_… för live. En testnyckel kan aldrig användas på live-data (och vice versa) – om de inte stämmer överens returneras 401 wrong_environment.

Omfattningar

Nycklar har uttryckliga behörighetsomfång med minsta möjliga behörighet. En begäran som saknar det erforderliga behörighetsomfånget returnerar 403 insufficient_scope.

Omfattning	Bemyndiganden
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.

Att förvara nycklar säkert

Hemliga nycklar är endast avsedda för server-till-server-kommunikation. Bädda aldrig in en hemlig nyckel i webbläsar- eller mobilkod, ett offentligt arkiv eller ett klientbundle. Om en nyckel exponeras ska du omedelbart byta ut den i Partner Center.

Kärn-API

Endpunkter

Obligatoriska fält är markerade med *. I exemplen används platshållare för autentiseringsuppgifter – aldrig riktiga nycklar.

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

Begäran

Body (application/json)

Fält	Typ	Beskrivning
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.

Exempel på förfrågan

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

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

Fel

Status	Kod	När
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.

Dessutom de vanliga autentiserings-, behörighets- och hastighetsbegränsningsfelen – se Fel och omförsök.

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 krävs

Begäran

Body (application/json)

Fält	Typ	Beskrivning
upload_ref*	string	The `upload_ref` from Upload a photo.
spec_id*	string	The `photo_specification` id (`spc_…`) to render against.

Exempel på förfrågan

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

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

Fel

Status	Kod	När
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.

Dessutom de vanliga autentiserings-, behörighets- och hastighetsbegränsningsfelen – se Fel och omförsök.

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

Begäran

Sökvägsparametrar

Fält	Typ	Beskrivning
id*	string	Session id.

Exempel på förfrågan

curl

curl "https://partner.svoyager.com/v1/photo-sessions/3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10" \
  -H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx"

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

Fel

Status	Kod	När
404	session_not_found	No session matches the id for this account/environment.

Dessutom de vanliga autentiserings-, behörighets- och hastighetsbegränsningsfelen – se Fel och omförsök.

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.readReturnerar bildbytes

Begäran

Sökvägsparametrar

Fält	Typ	Beskrivning
id*	string	Session id.

Returns raw `image/*` bytes on success (not JSON).

Exempel på förfrågan

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

Svar · 200

Vid lyckat resultat strömmar slutpunkten råa bildbytes (inte JSON). Spara svarsinnehållet i en fil.

Fel

Status	Kod	När
404	preview_not_found	The session or its preview does not exist.

Dessutom de vanliga autentiserings-, behörighets- och hastighetsbegränsningsfelen – se Fel och omförsök.

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 krävs

Begäran

Sökvägsparametrar

Fält	Typ	Beskrivning
id*	string	Session id to finalize.

Exempel på förfrågan

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"

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

Fel

Status	Kod	När
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.

Dessutom de vanliga autentiserings-, behörighets- och hastighetsbegränsningsfelen – se Fel och omförsök.

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

Begäran

Sökvägsparametrar

Fält	Typ	Beskrivning
id*	string	Order id.

Exempel på förfrågan

curl

curl "https://partner.svoyager.com/v1/orders/8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284" \
  -H "Authorization: Bearer svoy_sk_live_A8m4Qz1YOURKEYHERExxxxxxx"

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

Fel

Status	Kod	När
404	order_not_found	No order matches the id for this account/environment.

Dessutom de vanliga autentiserings-, behörighets- och hastighetsbegränsningsfelen – se Fel och omförsök.

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.readReturnerar bildbytes

Begäran

Sökvägsparametrar

Fält	Typ	Beskrivning
id*	string	Order id.

Returns raw `image/*` bytes on success (not JSON).

Exempel på förfrågan

curl

curl "https://partner.svoyager.com/v1/orders/8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284/final" \
  -H "Authorization: Bearer svoy_sk_live_A8m4Qz1YOURKEYHERExxxxxxx" \
  --output final.jpg

Svar · 200

Vid lyckat resultat strömmar slutpunkten råa bildbytes (inte JSON). Spara svarsinnehållet i en fil.

Fel

Status	Kod	När
404	final_not_found	The order or its final does not exist.

Dessutom de vanliga autentiserings-, behörighets- och hastighetsbegränsningsfelen – se Fel och omförsök.

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

Begäran

Frågeparametrar

Fält	Typ	Beskrivning
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`.

Exempel på förfrågan

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"

Svar · 200

200 · application/json

{
  "object": "list",
  "data": [
    {
      "object": "photo_specification",
      "id": "spc_9wTv2c1Kd8Qe",
      "name": "United States Passport"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Fel

Denna slutpunkt returnerar endast standardfelen nedan.

Dessutom de vanliga autentiserings-, behörighets- och hastighetsbegränsningsfelen – se Fel och omförsök.

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

Begäran

Sökvägsparametrar

Fält	Typ	Beskrivning
id*	string	Specification id (`spc_…`).

Exempel på förfrågan

curl

curl "https://partner.svoyager.com/v1/photo-specifications/spc_9wTv2c1Kd8Qe" \
  -H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx"

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

Fel

Status	Kod	När
404	spec_not_found	No active specification matches the id.

Dessutom de vanliga autentiserings-, behörighets- och hastighetsbegränsningsfelen – se Fel och omförsök.

Idempotens och säkra omförsök

Skicka en Idempotency-Key-rubrik (ett unikt värde, t.ex. en UUID) så att en omförsökt begäran aldrig debiteras eller bearbetas två gånger. Det krävs vid:

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

• Samma nyckel + samma innehåll → det ursprungliga resultatet återges (ingen andra avgift, ingen andra rendering).
• Samma nyckel + ett annat innehåll → 409 idempotency_key_reuse.
• Ett fel som går att återförsöka gör att du kan försöka igen med samma nyckel, body och upload_ref.
• Samtidiga slutföringsförfrågningar för en session kan aldrig skapa eller debitera två order.

Sessionens och orderns livscykel

En session går igenom olika förhandsgranskningsstadier; en order går igenom olika slutförandestadier.

Sessionsstatus

preview_ready — Förhandsgranskning genererad, inga problem.
preview_has_issues — Förhandsgranskning genererad med fel.
preview_failed — Förhandsgranskningen kunde inte genereras.
finalized — sessionen avslutades.

Orderstatus

final_ready — slutversionen är tillgänglig.
processing — Slutversionen håller på att förberedas.
failed — Finaliseringen misslyckades.

Testmiljö vs. produktionsmiljö

Miljön bestäms av ditt nyckelprefix – klienter kan aldrig skicka det. I testläget körs den riktiga förhandsvisningen med vattenstämpel så att du kan öva på det verkliga flödet, men det emulerar det slutgiltiga resultatet så att ingen livekvot eller produktionsrendering används.

Aspekt	Test	Live
livemode	false	true
Förhandsgranska	Äkta, med vattenstämpel	Äkta, med vattenstämpel
Slutlig	Sandbox-emulerad från förhandsvisningen	Äkta, utan vattenstämpel
sandbox_emulated	true	false
watermarked	true	false
Förbrukad kvot	Endast testkvot	Endast live-kvot

Kvoter och användning

Din plan inkluderar ett antal förhandsgranskningar och slutgiltiga versioner per period, som räknas separat. Att skapa en session förbrukar en förhandsgranskning; att slutföra förbrukar en slutgiltig version. Kvoten reserveras automatiskt innan bearbetningen påbörjas.

När den inkluderade förhandsgranskningen eller den slutliga kvoten är förbrukad returnerar begäran 402 quota_exceeded.
402 innebär ett definitivt stopp – ett nytt försök kommer inte att lyckas förrän nästa period eller vid en planändring.
Test- och produktionskvoter är helt oberoende av varandra.

Fel och omförsök

Varje fel använder ett kuvert. Request_id visas även i svarshuvudet X-Request-Id – inkludera det i supportförfrågningar.

Error envelope

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

Standardfel (alla slutpunkter)

Status	Kod	När
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 returneras endast vid ett bekräftat bildproblem. 402 innebär att kvoten är förbrukad. 409 är en idempotens- eller resurskonflikt.

429 betyder att du har nått hastighetsbegränsningen per nyckel – följ Retry-After-rubriken. För 502/503 och andra 5xx-fel, försök igen med backoff och samma Idempotency-Key.

Felkoder för foton

En förhandsgranskning kan returnera noll eller flera problem, vart och ett bestående av en stabil kod + ett meddelande. Visa dessa för slutanvändaren så att denne kan ta om bilden. En okänd uppströmssignal nedgraderas till ”other”.

Kod	Meddelande
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.

Filer, lagringstid och integritet

• Förhandsvisningar och slutgiltiga versioner tillhandahålls endast från autentiserade URL:er som hostas av SVOYAGER. Åtkomst kräver din API-nyckel och rätt omfattning – den underliggande lagringen exponeras aldrig offentligt.
• Uppladdade bilder är privata och begränsade till ditt konto och din miljö; uppladdningsmål är kortlivade och avsedda för engångsbruk.
• Dokumentfoton bearbetas för att skapa ditt resultat och delas inte mellan konton.

Se SVOYAGER:s villkor för databehandling, lagring och radering:Integritetspolicy ·Partneravtal och villkor

SVOYAGER ID Photo API

Översikt

Vad det gör

Förhandsgranskning → slutgiltigt arbetsflöde

Snabbstart

Bas-URL och miljöer

Autentisering

API-nycklar

Omfattningar

Att förvara nycklar säkert

Endpunkter

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

Idempotens och säkra omförsök

Sessionens och orderns livscykel

Testmiljö vs. produktionsmiljö

Kvoter och användning

Fel och omförsök

Felkoder för foton

Filer, lagringstid och integritet