ID PhotoREST · JSONOpenAPI 3.1

SVOYAGER ID Photo API

Gør ethvert foto til et ID-, pas- eller visumfoto, der overholder kravene.

SVOYAGER ID Photo API forvandler et almindeligt portræt til et dokumentfoto, der overholder kravene. ID Photo er et enkelt produkt: pas, visum, opholdstilladelse og nationalt ID er repræsenteret som dokumentspecifikationer, ikke som separate produkter. Du uploader et foto, genererer en forhåndsvisning med vandmærke i henhold til en specifikation og færdiggør derefter for at få resultatet uden vandmærke.

Forhåndsvisning → endelig arbejdsgang

1Upload et foto. Opret en upload-destination, og send billedets bytes til den.
2Opret en session. Vis en forhåndsvisning med vandmærke i forhold til en specifikation. Gennemgå de returnerede problemer.
3Afslut. Konverter den gennemgåede session til en bestilling, og modtag den endelige version uden vandmærke.

Hurtigstart

Hver anmodning autentificeres med en Bearer-hemmelig nøgle. Start i testtilstand:

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"

Base-URL og miljøer

Alle endpoints betjenes under en enkelt basis-URL:

Base URL

https://partner.svoyager.com/v1

Der er ingen miljøsti eller -parameter. Om en anmodning kører i test- eller live-tilstand bestemmes udelukkende af dit API-nøglepræfiks (svoy_sk_test_… vs. svoy_sk_live_…). Svarene gentager dette som livemode.

Autentificering

API-nøgler

Autentificer hver anmodning med en Authorization-header, der indeholder din hemmelige nøgle. Nøgler oprettes og udskiftes i Partner Center.

Header

Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx

Præfikset angiver miljøet: svoy_sk_test_… til test, svoy_sk_live_… til live. En testnøgle kan aldrig anvendes på live-data (og omvendt) — uoverensstemmelser returnerer 401 wrong_environment.

Omfang

Nøgler har eksplicitte anvendelsesområder med mindst mulig adgang. En anmodning, der mangler det krævede anvendelsesområde, returnerer 403 insufficient_scope.

Omfang	Tildelinger
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.

Opbevaring af nøgler på en sikker måde

Hemmelige nøgler er udelukkende til brug mellem servere. Indsæt aldrig en hemmelig nøgle i browser- eller mobilkode, et offentligt repository eller en klient-side-pakke. Hvis en nøgle bliver afsløret, skal du straks udskifte den i Partner Center.

Core API

Endpunkter

Obligatoriske felter er markeret med *. Eksemplerne bruger pladsholder-legitimationsoplysninger — aldrig rigtige nøgler.

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

Anmodning

Brødtekst (application/json)

Felt	Type	Beskrivelse
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.

Eksempel på anmodning

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

Fejl

Status	Kode	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.

Derudover de standardfejl, der vedrører autentificering, tilladelser og hastighedsbegrænsninger — se Fejl og gentagelser.

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 påkrævet

Anmodning

Brødtekst (application/json)

Felt	Type	Beskrivelse
upload_ref*	string	The `upload_ref` from Upload a photo.
spec_id*	string	The `photo_specification` id (`spc_…`) to render against.

Eksempel på anmodning

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

Fejl

Status	Kode	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.

Derudover de standardfejl, der vedrører autentificering, tilladelser og hastighedsbegrænsninger — se Fejl og gentagelser.

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

Anmodning

Sti-parametre

Felt	Type	Beskrivelse
id*	string	Session id.

Eksempel på anmodning

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

Fejl

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

Derudover de standardfejl, der vedrører autentificering, tilladelser og hastighedsbegrænsninger — se Fejl og gentagelser.

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.readReturnerer billedbytes

Anmodning

Sti-parametre

Felt	Type	Beskrivelse
id*	string	Session id.

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

Eksempel på anmodning

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

Ved succes sender endpointet rå billedbytes (ikke JSON). Gem svarets indhold i en fil.

Fejl

Status	Kode	Når
404	preview_not_found	The session or its preview does not exist.

Derudover de standardfejl, der vedrører autentificering, tilladelser og hastighedsbegrænsninger — se Fejl og gentagelser.

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 påkrævet

Anmodning

Sti-parametre

Felt	Type	Beskrivelse
id*	string	Session id to finalize.

Eksempel på anmodning

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

Fejl

Status	Kode	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.

Derudover de standardfejl, der vedrører autentificering, tilladelser og hastighedsbegrænsninger — se Fejl og gentagelser.

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

Anmodning

Sti-parametre

Felt	Type	Beskrivelse
id*	string	Order id.

Eksempel på anmodning

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

Fejl

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

Derudover de standardfejl, der vedrører autentificering, tilladelser og hastighedsbegrænsninger — se Fejl og gentagelser.

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.readReturnerer billedbytes

Anmodning

Sti-parametre

Felt	Type	Beskrivelse
id*	string	Order id.

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

Eksempel på anmodning

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

Ved succes sender endpointet rå billedbytes (ikke JSON). Gem svarets indhold i en fil.

Fejl

Status	Kode	Når
404	final_not_found	The order or its final does not exist.

Derudover de standardfejl, der vedrører autentificering, tilladelser og hastighedsbegrænsninger — se Fejl og gentagelser.

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

Anmodning

Forespørgselsparametre

Felt	Type	Beskrivelse
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`.

Eksempel på anmodning

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
}

Fejl

Dette endpoint returnerer kun nedenstående standardfejl.

Derudover de standardfejl, der vedrører autentificering, tilladelser og hastighedsbegrænsninger — se Fejl og gentagelser.

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

Anmodning

Sti-parametre

Felt	Type	Beskrivelse
id*	string	Specification id (`spc_…`).

Eksempel på anmodning

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

Fejl

Status	Kode	Når
404	spec_not_found	No active specification matches the id.

Derudover de standardfejl, der vedrører autentificering, tilladelser og hastighedsbegrænsninger — se Fejl og gentagelser.

Idempotens og sikre gentagelser

Send en Idempotency-Key-header (en unik værdi, f.eks. en UUID), så en gentaget anmodning aldrig medfører dobbeltopkrævning eller dobbeltbehandling. Dette er påkrævet ved:

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

• Samme nøgle + samme indhold → det oprindelige resultat afspilles igen (ingen ekstra belastning, ingen ekstra gengivelse).
• Samme nøgle + en anden body → 409 idempotency_key_reuse.
• En fejl, der kan forsøges igen, giver dig mulighed for at prøve igen med den samme nøgle, body og upload_ref.
• Samtidige afslutningsanmodninger for én session kan aldrig oprette eller debitere to ordrer.

Session og ordrens livscyklus

En session gennemgår forhåndsvisningsstadier; en ordre gennemgår færdiggørelsesstadier.

Sessionsstatus

preview_ready — Forhåndsvisning genereret, ingen problemer.
preview_has_issues — Forhåndsvisning genereret med fejl.
preview_failed — Det var ikke muligt at generere forhåndsvisningen.
finalized — sessionen blev afsluttet.

Ordrestatus

final_ready — Den endelige version er tilgængelig.
processing — Den endelige version er under udarbejdelse.
failed — Finaliseringen mislykkedes.

Test vs. live

Miljøet bestemmes af dit nøglepræfiks — klienter kan aldrig videregive det. I testtilstand vises den rigtige forhåndsvisning med vandmærke, så du kan gennemgå den reelle proces, men den emulerer den endelige version, så der ikke bruges live-kvoter eller produktionsrendering.

Aspect	Test	Live
livemode	false	true
Eksempel	Ægte, med vandmærke	Ægte, med vandmærke
Afslutning	Sandbox-emuleret fra forhåndsvisningen	Ægte, uden vandmærke
sandbox_emulated	true	false
watermarked	true	false
Forbrugt kvote	Kun testkvote	Gælder kun live-kvote

Kvoter og forbrug

Din plan inkluderer et antal forhåndsvisninger og endelige oversættelser pr. periode, der tælles separat. Oprettelse af en session bruger én forhåndsvisning; færdiggørelse bruger én endelig oversættelse. Kvoten reserveres atomisk før behandlingen.

Når den inkluderede forhåndsvisning eller den endelige kvote er opbrugt, returnerer anmodningen 402 quota_exceeded.
402 er en hård stopkode — gentagelse vil ikke lykkes før den næste periode eller en ændring af abonnementet.
Test- og live-kvoter er fuldstændig uafhængige af hinanden.

Fejl og gentagelser

Hver fejl bruger én konvolut. Request_id vises også i svarheaderen X-Request-Id — medtag den i supportanmodninger.

Error envelope

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

Standardfejl (alle endpoints)

Status	Kode	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 returneres kun ved et bekræftet billedproblem. 402 betyder, at kvoten er opbrugt. 409 angiver en idempotens- eller ressourcekonflikt.

429 betyder, at du har nået hastighedsgrænsen pr. nøgle — overhold Retry-After-headeren. Ved 502/503 og andre 5xx-fejl skal du prøve igen med backoff og den samme Idempotency-Key.

Fotoproblemkoder

En forhåndsvisning kan returnere nul eller flere problemer, hvor hvert problem består af en stabil kode + en besked. Vis disse til slutbrugeren, så vedkommende kan tage billedet igen. Et ukendt upstream-signal nedgraderes til »other«.

Kode	Meddelelse
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, opbevaring og privatliv

• Forhåndsvisninger og endelige versioner leveres udelukkende fra SVOYAGER-hostede, godkendte URL'er. Adgang kræver din API-nøgle og det korrekte anvendelsesområde — den underliggende lagring bliver aldrig offentliggjort.
• Uploaded billeder er private og begrænset til din konto og dit miljø; upload-mål er kortvarige og til engangsbrug.
• Dokumentfotos behandles for at frembringe dit resultat og deles ikke på tværs af konti.

Se SVOYAGER’s vilkår for databehandling, opbevaring og sletning:Privatlivspolitik ·Partneraftale og vilkår

SVOYAGER ID Photo API

Oversigt

Hvad det gør

Forhåndsvisning → endelig arbejdsgang

Hurtigstart

Base-URL og miljøer

Autentificering

API-nøgler

Omfang

Opbevaring af nøgler på en sikker måde

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 og sikre gentagelser

Session og ordrens livscyklus

Test vs. live

Kvoter og forbrug

Fejl og gentagelser

Fotoproblemkoder

Filer, opbevaring og privatliv