ID PhotoREST · JSONOpenAPI 3.1

SVOYAGER ID Photo API

Gjør hvilket som helst bilde om til et godkjent ID-, pass- eller visumbilde.

SVOYAGER ID Photo API forvandler et vanlig portrett til et godkjent dokumentfoto. ID Photo er ett enkelt produkt: pass, visum, oppholdstillatelse og nasjonalt ID-kort er representert som dokumentspesifikasjoner, ikke separate produkter. Du laster opp et bilde, genererer en forhåndsvisning med vannmerke i henhold til en spesifikasjon, og fullfører deretter for å få resultatet uten vannmerke.

Forhåndsvisning → endelig arbeidsflyt

1Last opp et bilde. Opprett et opplastingsmål og send bildebytene til det.
2Opprett en økt. Vis en forhåndsvisning med vannmerke i henhold til en spesifikasjon. Gå gjennom de returnerte feilene.
3Fullfør. Konverter den gjennomgåtte økten til en bestilling og motta den endelige versjonen uten vannmerke.

Hurtigstart

Hver forespørsel autentiseres med en Bearer-hemmelig nøkkel. Start i testmodus:

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 endepunkter betjenes under én enkelt basis-URL:

Base URL

https://partner.svoyager.com/v1

Det finnes ingen miljøbane eller -parameter. Hvorvidt en forespørsel kjøres i test- eller live-modus, bestemmes utelukkende av prefikset til API-nøkkelen din (svoy_sk_test_… vs. svoy_sk_live_…). Svarene gjenspeiler dette som livemode.

Autentisering

API-nøkler

Autentiser hver forespørsel med en Authorization-overskrift som inneholder din hemmelige nøkkel. Nøklene opprettes og roteres i Partner Center.

Header

Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx

Prefikset angir miljøet: svoy_sk_test_… for test, svoy_sk_live_… for live. En testnøkkel kan aldri brukes på live-data (og omvendt) — uoverensstemmelser returnerer 401 wrong_environment.

Omfang

Nøkler har eksplisitte omfang med minst mulig privilegium. En forespørsel som mangler det nødvendige omfanget, 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.

Sikre nøklene

Hemmelige nøkler er kun for bruk mellom servere. Du må aldri legge inn en hemmelig nøkkel i nettleser- eller mobilkode, et offentlig arkiv eller en klientpakke. Hvis en nøkkel blir avslørt, må du umiddelbart bytte den ut i Partner Center.

Kjerne-API

Endepunkter

Obligatoriske felt er merket med *. Eksemplene bruker plassholderopplysninger – aldri ekte nøkler.

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

Forespørsel

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å forespørsel

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

Feil

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.

I tillegg kommer standardfeilene for autentisering, tillatelser og hastighetsbegrensning – se Feil og nye forsø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 er påkrevd

Forespørsel

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å forespørsel

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

Feil

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.

I tillegg kommer standardfeilene for autentisering, tillatelser og hastighetsbegrensning – se Feil og nye forsø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

Forespørsel

Stiparametere

Felt	Type	Beskrivelse
id*	string	Session id.

Eksempel på forespørsel

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

Feil

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

I tillegg kommer standardfeilene for autentisering, tillatelser og hastighetsbegrensning – se Feil og nye forsø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.readReturnerer bildebytes

Forespørsel

Stiparametere

Felt	Type	Beskrivelse
id*	string	Session id.

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

Eksempel på forespørsel

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 vellykket utførelse sender endepunktet rå bildebytes (ikke JSON). Lagre svarteksten i en fil.

Feil

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

I tillegg kommer standardfeilene for autentisering, tillatelser og hastighetsbegrensning – se Feil og nye forsø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 er påkrevd

Forespørsel

Stiparametere

Felt	Type	Beskrivelse
id*	string	Session id to finalize.

Eksempel på forespørsel

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

Feil

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.

I tillegg kommer standardfeilene for autentisering, tillatelser og hastighetsbegrensning – se Feil og nye forsø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

Forespørsel

Stiparametere

Felt	Type	Beskrivelse
id*	string	Order id.

Eksempel på forespørsel

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

Feil

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

I tillegg kommer standardfeilene for autentisering, tillatelser og hastighetsbegrensning – se Feil og nye forsø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.readReturnerer bildebytes

Forespørsel

Stiparametere

Felt	Type	Beskrivelse
id*	string	Order id.

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

Eksempel på forespørsel

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 vellykket utførelse sender endepunktet rå bildebytes (ikke JSON). Lagre svarteksten i en fil.

Feil

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

I tillegg kommer standardfeilene for autentisering, tillatelser og hastighetsbegrensning – se Feil og nye forsø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

Forespørsel

Spørringsparametere

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å forespørsel

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
}

Feil

Dette endepunktet returnerer kun standardfeilene nedenfor.

I tillegg kommer standardfeilene for autentisering, tillatelser og hastighetsbegrensning – se Feil og nye forsø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

Forespørsel

Stiparametere

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

Eksempel på forespørsel

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

Feil

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

I tillegg kommer standardfeilene for autentisering, tillatelser og hastighetsbegrensning – se Feil og nye forsøk.

Idempotens og sikre nye forsøk

Send en Idempotency-Key-header (en unik verdi, f.eks. en UUID) slik at en fornyet forespørsel aldri blir belastet eller behandlet to ganger. Dette er påkrevd ved:

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

• Samme nøkkel + samme innhold → det opprinnelige resultatet gjengis (ingen ny belastning, ingen ny gjengivelse).
• Samme nøkkel + en annen brødtekst → 409 idempotency_key_reuse.
• En feil som kan prøves på nytt lar deg prøve på nytt med samme nøkkel, body og upload_ref.
• Samtidige fullføringsforespørsler for én økt kan aldri opprette eller belaste to ordrer.

Sesjon og bestillingslivssyklus

En sesjon går gjennom forhåndsvisningsstadier; en ordre gjennom sluttføringsstadier.

Sesjonsstatus

preview_ready — Forhåndsvisning generert, ingen problemer.
preview_has_issues — Forhåndsvisning generert med feil.
preview_failed — Forhåndsvisningen kunne ikke genereres.
finalized — sesjonen ble avsluttet.

Orderstatus

final_ready — Den endelige versjonen er tilgjengelig.
processing — Den endelige versjonen er under utarbeidelse.
failed — Finaliseringen mislyktes.

Test vs. produksjon

Miljøet bestemmes av nøkkelprefikset ditt — klienter kan aldri endre det. Testmodus kjører den virkelige forhåndsvisningen med vannmerke, slik at du kan øve på den faktiske arbeidsflyten, men emulerer det endelige resultatet, slik at ingen live-kvote eller produksjonsrendering brukes.

Aspekt	Test	Live
livemode	false	true
Forhåndsvisning	Ekte, med vannmerke	Ekte, med vannmerke
Endelig	Sandbox-emulert fra forhåndsvisningen	Ekte, uten vannmerke
sandbox_emulated	true	false
watermarked	true	false
Brukt kvote	Kun testkvote	Gjelder kun live-kvote

Kvoter og bruk

Abonnementet ditt inkluderer et antall forhåndsvisninger og endelige versjoner per periode, som telles separat. Å opprette en økt bruker én forhåndsvisning; å fullføre bruker én endelig versjon. Kvoten reserveres automatisk før behandlingen.

Når den inkluderte forhåndsvisningen eller den endelige kvoten er oppbrukt, returnerer forespørselen 402 quota_exceeded.
402 er en hard stopp – nye forsøk vil ikke lykkes før neste periode eller en endring i abonnementet.
Test- og produksjonskvoter er helt uavhengige av hverandre.

Feil og nye forsøk

Hver feil bruker én konvolutt. Request_id vises også i svarhodet X-Request-Id – inkluder det i supportforespørsler.

Error envelope

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

Standardfeil (alle endepunkter)

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 bekreftet bildeproblem. 402 betyr at kvoten er oppbrukt. 409 er en idempotens- eller ressurskonflikt.

429 betyr at du har nådd hastighetsgrensen per nøkkel — følg Retry-After-overskriften. For 502/503 og andre 5xx-feil, prøv på nytt med backoff og den samme Idempotency-Key.

Koder for fotoproblemer

En forhåndsvisning kan returnere null eller flere feil, hver bestående av en stabilkode og en melding. Vis disse til sluttbrukeren slik at vedkommende kan ta bildet på nytt. Et ukjent oppstrømsignal nedgraderes til «other».

Kode	Melding
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, oppbevaring og personvern

• Forhåndsvisninger og endelige versjoner leveres kun fra autentiserte URL-er som er vert hos SVOYAGER. Tilgang krever din API-nøkkel og riktig omfang — den underliggende lagringen blir aldri offentliggjort.
• Opplastede bilder er private og begrenset til din konto og ditt miljø; opplastingsmålene er kortvarige og til engangsbruk.
• Dokumentbilder behandles for å gi deg resultatet, og deles ikke mellom kontoer.

Se SVOYAGER’ vilkår for databehandling, oppbevaring og sletting:Personvernpolicy ·Partneravtale og vilkår

SVOYAGER ID Photo API

Oversikt

Hva det gjør

Forhåndsvisning → endelig arbeidsflyt

Hurtigstart

Base-URL og miljøer

Autentisering

API-nøkler

Omfang

Sikre nøklene

Endepunkter

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 nye forsøk

Sesjon og bestillingslivssyklus

Test vs. produksjon

Kvoter og bruk

Feil og nye forsøk

Koder for fotoproblemer

Filer, oppbevaring og personvern