ID PhotoREST · JSONOpenAPI 3.1

SVOYAGER ID Photo API

Transforme qualquer foto em uma foto compatível para documento de identidade, passaporte ou visto.

O SVOYAGER ID Photo API transforma um retrato comum em uma foto de documento em conformidade. O ID Photo é um único produto: passaporte, visto, autorização de residência e identidade nacional são representados como especificações de documentos, não como produtos separados. Você faz o upload de uma foto, gera uma pré-visualização com marca d’água de acordo com uma especificação e, em seguida, finaliza o processo para obter o resultado sem marca d’água.

Pré-visualização → fluxo de trabalho final

1Envie uma foto. Crie um destino de upload e envie os bytes da imagem para ele.
2Crie uma sessão. Exiba uma pré-visualização com marca d’água de acordo com uma especificação. Analise os problemas retornados.
3Finalizar. Transforme a sessão revisada em um pedido e receba a versão final sem marca d’água.

Introdução rápida

Cada solicitação é autenticada com uma chave secreta Bearer. Comece no modo de teste:

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"

URL base e ambientes

Todos os endpoints são servidos sob uma única URL base:

Base URL

https://partner.svoyager.com/v1

Não há caminho ou parâmetro de ambiente. Se uma solicitação é executada no ambiente de teste ou em produção é determinado inteiramente pelo prefixo da sua chave de API (svoy_sk_test_… vs svoy_sk_live_…). As respostas refletem isso como livemode.

Autenticação

Chaves de API

Autentique todas as solicitações com um cabeçalho Authorization contendo sua chave secreta. As chaves são criadas e alternadas no Partner Center.

Header

Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx

O prefixo seleciona o ambiente: svoy_sk_test_… para teste, svoy_sk_live_… para produção. Uma chave de teste nunca pode atuar sobre dados de produção (e vice-versa) — incompatibilidades retornam o código 401 wrong_environment.

Escopos

As chaves possuem escopos explícitos de privilégios mínimos. Uma solicitação sem o escopo necessário retorna o código de status 403 (insufficient_scope).

Escopo	Concessões
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.

Mantendo as chaves em segurança

As chaves secretas são exclusivas para comunicação entre servidores. Nunca incorpore uma chave secreta no código do navegador ou de dispositivos móveis, em um repositório público ou em um pacote do lado do cliente. Se uma chave for exposta, altere-a imediatamente no Partner Center.

API principal

Endpoints

Os campos obrigatórios estão marcados com *. Os exemplos utilizam credenciais fictícias — nunca chaves reais.

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.

escopo photo.sessions.write

Solicitação

Corpo (application/json)

Campo	Tipo	Descrição
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.

Exemplo de solicitação

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

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

Erros

Status	Código	Quando
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.

Além disso, os erros padrão de autenticação, permissão e limite de taxa — consulte Erros e novas tentativas.

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.

escopo photo.sessions.write Idempotency-Key obrigatório

Solicitação

Corpo (application/json)

Campo	Tipo	Descrição
upload_ref*	string	The `upload_ref` from Upload a photo.
spec_id*	string	The `photo_specification` id (`spc_…`) to render against.

Exemplo de solicitação

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

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

Erros

Status	Código	Quando
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.

Além disso, os erros padrão de autenticação, permissão e limite de taxa — consulte Erros e novas tentativas.

GET/v1/photo-sessions/{id}

Retrieve a photo session

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

escopo photo.sessions.read

Solicitação

Parâmetros de caminho

Campo	Tipo	Descrição
id*	string	Session id.

Exemplo de solicitação

curl

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

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

Erros

Status	Código	Quando
404	session_not_found	No session matches the id for this account/environment.

Além disso, os erros padrão de autenticação, permissão e limite de taxa — consulte Erros e novas tentativas.

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.

escopo photo.sessions.readRetorna os bytes da imagem

Solicitação

Parâmetros de caminho

Campo	Tipo	Descrição
id*	string	Session id.

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

Exemplo de solicitação

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

Resposta · 200

Em caso de sucesso, o endpoint transmite os bytes brutos da imagem (não em JSON). Salve o corpo da resposta em um arquivo.

Erros

Status	Código	Quando
404	preview_not_found	The session or its preview does not exist.

Além disso, os erros padrão de autenticação, permissão e limite de taxa — consulte Erros e novas tentativas.

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.

escopo photo.finalize.write Idempotency-Key obrigatório

Solicitação

Parâmetros de caminho

Campo	Tipo	Descrição
id*	string	Session id to finalize.

Exemplo de solicitação

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"

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

Erros

Status	Código	Quando
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.

Além disso, os erros padrão de autenticação, permissão e limite de taxa — consulte Erros e novas tentativas.

GET/v1/orders/{id}

Retrieve an order

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

escopo photo.orders.read

Solicitação

Parâmetros de caminho

Campo	Tipo	Descrição
id*	string	Order id.

Exemplo de solicitação

curl

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

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

Erros

Status	Código	Quando
404	order_not_found	No order matches the id for this account/environment.

Além disso, os erros padrão de autenticação, permissão e limite de taxa — consulte Erros e novas tentativas.

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.

escopo photo.orders.readRetorna os bytes da imagem

Solicitação

Parâmetros de caminho

Campo	Tipo	Descrição
id*	string	Order id.

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

Exemplo de solicitação

curl

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

Resposta · 200

Em caso de sucesso, o endpoint transmite os bytes brutos da imagem (não em JSON). Salve o corpo da resposta em um arquivo.

Erros

Status	Código	Quando
404	final_not_found	The order or its final does not exist.

Além disso, os erros padrão de autenticação, permissão e limite de taxa — consulte Erros e novas tentativas.

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.

escopo photo.specs.read

Solicitação

Parâmetros de consulta

Campo	Tipo	Descrição
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`.

Exemplo de solicitação

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"

Resposta · 200

200 · application/json

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

Erros

Este endpoint retorna apenas os erros padrão listados abaixo.

Além disso, os erros padrão de autenticação, permissão e limite de taxa — consulte Erros e novas tentativas.

GET/v1/photo-specifications/{id}

Retrieve a photo specification

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

escopo photo.specs.read

Solicitação

Parâmetros de caminho

Campo	Tipo	Descrição
id*	string	Specification id (`spc_…`).

Exemplo de solicitação

curl

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

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

Erros

Status	Código	Quando
404	spec_not_found	No active specification matches the id.

Além disso, os erros padrão de autenticação, permissão e limite de taxa — consulte Erros e novas tentativas.

Idempotência e novas tentativas seguras

Envie um cabeçalho Idempotency-Key (um valor único, por exemplo, um UUID) para que uma solicitação repetida nunca seja cobrada ou processada duas vezes. É obrigatório em:

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

• Mesma chave + mesmo corpo → o resultado original é reproduzido (sem cobrança adicional, sem renderização adicional).
• Mesma chave + corpo diferente → 409 idempotency_key_reuse.
• Uma falha que permite repetição permite que você tente novamente com a mesma chave, corpo e upload_ref.
• Solicitações simultâneas de finalização para uma sessão nunca podem criar ou cobrar dois pedidos.

Ciclo de vida da sessão e do pedido

Uma sessão passa por estados de visualização; um pedido, por estados de finalização.

Status da sessão

preview_ready — Pré-visualização gerada, sem problemas.
preview_has_issues — visualização gerada com erros.
preview_failed — Não foi possível gerar a visualização.
finalized — a sessão foi encerrada.

Status do pedido

final_ready — A versão final está disponível.
processing — A versão final está sendo preparada.
failed — Falha na finalização.

Teste x produção

O ambiente é determinado pelo prefixo da sua chave — os clientes nunca podem alterá-lo. O modo de teste exibe a pré-visualização real com marca d’água para que você possa testar o fluxo real, mas emula o resultado final, de modo que nenhuma cota ativa ou renderização de produção seja utilizada.

Aspect	Teste	Ao vivo
livemode	false	true
Pré-visualização	Real, com marca d’água	Real, com marca d’água
Final	Sandbox emulada a partir da pré-visualização	Real, sem marca d’água
sandbox_emulated	true	false
watermarked	true	false
Cota consumida	Apenas cota de teste	Apenas cota ativa

Cotas e uso

Seu plano inclui um número determinado de pré-visualizações e versões finais por período, contadas separadamente. Criar uma sessão consome uma pré-visualização; finalizar consome uma versão final. A cota é reservada de forma atômica antes do processamento.

Quando a cota de pré-visualização ou a cota final incluída for esgotada, a solicitação retorna 402 quota_exceeded.
O código 402 é um bloqueio definitivo — novas tentativas não serão bem-sucedidas até o próximo período ou até que haja uma mudança no plano.
As cotas de teste e de produção são totalmente independentes.

Erros e novas tentativas

Cada erro utiliza um envelope. O request_id também aparece no cabeçalho de resposta X-Request-Id — inclua-o nas solicitações de suporte.

Error envelope

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

Erros padrão (todos os endpoints)

Status	Código	Quando
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`.

O código 422 é retornado apenas em caso de problema confirmado com a imagem. O código 402 significa que a cota foi esgotada. O código 409 indica um conflito de idempotência ou de recurso.

429 significa que você atingiu o limite de taxa por chave — respeite o cabeçalho Retry-After. Para 502/503 e outros códigos 5xx, tente novamente com intervalo de espera e a mesma Idempotency-Key.

Códigos de problemas de fotos

Uma pré-visualização pode retornar zero ou mais problemas, cada um composto por um código estável + mensagem. Apresente-os ao usuário final para que ele possa refazer a foto. Um sinal de upstream não reconhecido é reclassificado como “outro”.

Código	Mensagem
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.

Arquivos, retenção e privacidade

• Pré-visualizações e versões finais são fornecidas apenas a partir de URLs autenticadas e hospedadas pela SVOYAGER. O acesso requer sua chave de API e o escopo correto — o armazenamento subjacente nunca é exposto publicamente.
• As imagens enviadas são privadas e restritas à sua conta e ao seu ambiente; os destinos de envio têm vida curta e são de uso único.
• As fotos dos documentos são processadas para gerar seu resultado e não são compartilhadas entre contas.

Consulte os termos de processamento, retenção e exclusão de dados da SVOYAGER:Política de Privacidade ·Contrato e Termos de Parceria

SVOYAGER ID Photo API

Visão geral

O que isso faz

Pré-visualização → fluxo de trabalho final

Introdução rápida

URL base e ambientes

Autenticação

Chaves de API

Escopos

Mantendo as chaves em segurança

Endpoints

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

Idempotência e novas tentativas seguras

Ciclo de vida da sessão e do pedido

Teste x produção

Cotas e uso

Erros e novas tentativas

Códigos de problemas de fotos

Arquivos, retenção e privacidade