DEV Community: whitetirocket

I open-sourced passport photo specs for 100 countries (MIT, JSON, public API)

whitetirocket — Wed, 13 May 2026 19:05:42 +0000

I open-sourced passport photo specs for 100 countries (MIT, JSON, public API)

If you have ever built anything that touches passport or visa photos, you know the boring part is not the face detection or the background segmentation. It is the country specifications. Every country has slightly different size. Different background color. Different file size cap on the upload portal. A different head-height ratio. The documentation is scattered across consulate websites in 12 languages, half of which 404 every six months.

I have been maintaining this dataset for a year while building IDPhotoSnap, a free browser-only passport photo tool. Last week I published the whole thing as an open repository at github.com/whitetirocket/passport-photo-specs.

MIT licensed. JSON, TypeScript, and Python bindings. 100 countries. 248 document formats. Public HTTP API at idphotosnap.com/api/specs with no auth and CORS open.

This post is for the next person building anything in this category - you can skip the country-spec research entirely and focus on the actual product.

What is in it

Each country entry has documents (passport, visa, ID card, driving licence, residence permit). Each document has:

interface DocumentSpec {
  id: string             // 'italy-visa'
  name: string           // 'Visa'
  slug: string           // 'italy-visa-photo'
  widthMm: number        // 35
  heightMm: number       // 45
  widthPx: number        // 413 (at given DPI)
  heightPx: number       // 531
  dpi: number            // 300
  background: string     // 'Plain light grey'
  bgColor: string        // '#eeeeee' (hex)
  bgColorLabel: string   // 'Light grey'
  requirements: string[] // ['Plain light grey background', ...]
}

interface CountrySpec {
  id: string
  name: string
  flag: string
  documents: DocumentSpec[]
}

Three ways to use it

1. HTTP API (no clone)

# Full dataset (Schema.org Dataset JSON-LD wrapped)
curl https://idphotosnap.com/api/specs

# Filter to one country
curl "https://idphotosnap.com/api/specs?country=china&format=raw"

# Plain JSON (no JSON-LD wrapper)
curl https://idphotosnap.com/api/specs?format=raw

No auth. CORS open. Edge-cached 1 hour. Use in production without permission.

2. NPM-style import

// npm install github:whitetirocket/passport-photo-specs
import { findDocument, findCountry } from 'passport-photo-specs'

const chinaVisa = findDocument('china-visa-photo')
// { widthMm: 33, heightMm: 48, ... }

const india = findCountry('india')
// All India docs: passport, visa, OCI, PAN card, PCC, driving licence, voter ID

3. Plain JSON in any language

The complete dataset is at specs/specs.json (174 KB). Examples for Python, Go, and Rust are in examples/ - they show the three most common patterns: filter to one country, lookup by slug, validate spec consistency.

Why I bothered

Most passport photo tools claim "200+ countries supported" or "900+ document types". When you check what that means, two patterns appear:

They have one default spec (35x45mm, white background, ICAO 9303) and apply it as a fallback for every country that has not been independently validated. So "200 countries" is really "30 verified plus 170 ICAO defaults".
They scrape specs from each other rather than from the original government source. When a country updates its requirements (which happens every few years), the change takes 6-12 months to propagate.

For a real passport application this matters. A wrong photo gets rejected at the consulate, application delayed by days or weeks. The user paid $15 for the photo at a drugstore plus $200 for the visa, and the photo is the part that fails.

I wanted a single source of truth I could verify against government documentation directly.

Notable specs that catch tool builders

If you are building something in this category, these formats are commonly mis-specified across the ecosystem:

Chinese visa is 33x48mm, not 35x45 like Schengen, not square like US. Unique format.
Chinese visa COVA portal wants file size 40 KB to 1 MB, JPG only, 354x472 px minimum.
US DS-160 visa upload caps files at 240 KB. Square 600x600 minimum, 1200x1200 maximum.
Indian Sarathi driving licence requires 20-50 KB file size window (under or over both fail silently).
Indian PAN card is 25x35mm at 200x230 px maximum, 10-300 KB.
UK passport accepts light grey background in addition to white. One of few that does. Glasses banned since 2018.
German Personalausweis has a May 2025 rule requiring digital-only photos via Buergeramt for German citizens. Separate from German Schengen visa for foreign applicants, which still accepts standard 35x45mm digital photos.

These are the dataset's biggest non-obvious wins. If your tool gets these seven right, you cover the meaningfully different cases.

Validation methodology

For each country, I checked at least one of these sources:

US Department of State (travel.state.gov)
UK HM Passport Office (gov.uk/photos-for-passports)
German Bundesdruckerei + Auswaertiges Amt
Italian Polizia di Stato + Questura
French ANTS (ants.gouv.fr)
Spanish Ministerio de Asuntos Exteriores
Canadian IRCC (Immigration, Refugees and Citizenship Canada)
Australian Department of Foreign Affairs and Trade
Indian Passport Seva Kendra (passportindia.gov.in)
Indian RTO / Sarathi / Parivahan portals
Chinese Ministry of Foreign Affairs (cova.cs.mfa.gov.cn)
Japanese Ministry of Foreign Affairs (mofa.go.jp)
Schengen visa code Annex 11 (ICAO 9303)
EU Entry/Exit System (EES) specifications
New Zealand DIA (passports.govt.nz)
Brazilian Polícia Federal
Mexican SRE (gob.mx)

Beyond top-20 countries, I follow the ICAO 9303 default unless an official source documents a country-specific deviation. I do not pad the dataset with synthetic country variants. If a country's photo spec is identical to ICAO 9303 default, it is marked as such rather than counted as "unique".

This means the 100 country count is honest. I could have called it 193 (all ICAO member states) and claimed parity with competitors. I chose not to.

Architecture (in case you are building something similar)

The companion tool, IDPhotoSnap, runs the whole pipeline in the browser:

Face landmark detection via face-api.js (TF.js + WASM)
Background segmentation via BRIA RMBG-1.4 (ONNX Runtime Web)
Geometric cropping + JPEG export via Canvas API
Print-ready PDF via jsPDF

The photo never reaches a server. Verifiable in browser DevTools Network tab during the workflow - zero photo uploads, only static assets and ML model weights.

This matters because passport photos are biometric data under GDPR Article 9, Illinois BIPA, Texas CUBI, India DPDP Act 2023. Server-based architecture inherits compliance obligations; browser-only sidesteps the whole chain.

If you want a deeper writeup on the browser-only architecture and how to verify the claim, my privacy-first explainer covers the DevTools test in detail.

What I want from this

If you find a spec that is wrong, open an issue with a link to the official government source. If you want to add a country I do not have, open a PR with the spec plus the citation.

I will not accept specs copied from other photo tool aggregators. Government sources only - this is the data quality discipline that keeps the dataset from drifting into the same marketing inflation as the rest of the category.

Used in production

The dataset powers IDPhotoSnap. If you build something else with it, open a PR adding your project to the "Used by" section of the README.

Validating Passport Photos for 3 of the Strictest Government Portals (India, China, US)

whitetirocket — Mon, 11 May 2026 06:24:16 +0000

Validating Passport Photos for 3 of the Strictest Government Portals (India, China, US)

Passport photo validation looks like a solved problem. Crop to the country spec, slap on a white background, save as JPG. Done.

Then you start submitting to actual government portals and discover that each one has its own undocumented edge cases that reject otherwise correct photos. The crop is right. The background is right. The portal still rejects.

I run a free browser-based passport photo tool covering 85+ countries. Building country-specific validation has surfaced some genuinely strange constraints. Here are the three that taught me the most: India's Sarathi/Parivahan, China's COVA, and the US DS-160.

India: Sarathi and Parivahan portals

The Indian Ministry of Road Transport and Highways runs two portals for driving licenses and vehicle registration: Sarathi (for citizens) and Parivahan (the umbrella service). Both accept passport-style photos for license applications.

Documented spec:

35 x 45 mm
Plain white background
JPG only

Undocumented constraint that catches every tool I have tested:

File size must be 20 to 50 KB

Not 50 KB max. A 20 KB minimum too. A clean photo from a modern phone, properly cropped to 35 x 45 mm at 300 DPI, lands at 80-150 KB. The portal silently rejects anything above 50 KB with a generic error like "image format not accepted".

The actual fix is JPEG quality compression, but you cannot just lower the quality slider blindly. At quality 60, the file size hits the range but Sarathi's automated face detection rejects "low image quality". At quality 75, the file is 60-70 KB and still rejected. The narrow window is quality 70 with subsampling 4:2:0 and progressive encoding off.

// Browser-side compression for Sarathi/Parivahan
async function compressForSarathi(canvas) {
  let quality = 0.70
  for (let attempt = 0; attempt < 5; attempt++) {
    const blob = await new Promise(r => canvas.toBlob(r, 'image/jpeg', quality))
    if (blob.size >= 20_000 && blob.size <= 50_000) return blob
    quality += blob.size > 50_000 ? -0.05 : 0.03
  }
  throw new Error('Could not hit Sarathi 20-50 KB window')
}

The PAN card portal is similar: 25 x 35 mm size, but with a different range (10 to 300 KB) and no minimum on dimensions, only a 200 x 230 px maximum.

For the validated DIY workflow see the Indian driving license photo tool which auto-fits the 20-50 KB window before output.

China: COVA online visa portal

The China Online Visa Application portal (cova.cs.mfa.gov.cn) is the modern alternative to the 2 printed photos at a CVASC visa center. Foreigners applying for a Chinese visa from anywhere in the world upload through the same system.

Documented spec:

33 x 48 mm (note: not 35 x 45)
Pure white background
JPG only
354 x 472 px minimum
40 KB to 1 MB file size

Undocumented:

The portal validates background uniformity by sampling pixels in 4 corners. If any corner pixel is not in the range R[245-255] G[245-255] B[245-255], it returns error E002.
Eyes must be detected as fully open. Even slightly squinted photos return E003.
The face must occupy 60-70% of frame height. Anything below 55% or above 75% returns E001 even though the file dimensions are correct.

The corner pixel check matters because most "white" backgrounds in real photos are slightly off-white from ambient light. A photo taken against a true-white wall in your living room often has corners reading R[238-242] - looks white to a human, fails the COVA validator.

The workaround is post-processing the background to pure #FFFFFF after segmentation:

function flattenBackgroundToPureWhite(imageData, mask) {
  for (let i = 0; i < imageData.data.length; i += 4) {
    const idx = i / 4
    if (mask[idx] < 0.5) {  // pixel is background
      imageData.data[i]     = 255  // R
      imageData.data[i + 1] = 255  // G
      imageData.data[i + 2] = 255  // B
    }
  }
  return imageData
}

Background segmentation runs on BRIA RMBG-1.4 in WebAssembly. Once the mask is computed, flattening to pure white is cheap. The visa-specific validator is at the China visa photo tool.

US DS-160: the 240 KB cap

The US State Department's DS-160 form for nonimmigrant visa applications has the strictest documented file size cap of any major portal:

240 KB maximum for the photo upload

That is below the natural file size of a properly cropped 600 x 600 px JPG at any reasonable quality setting. The portal also enforces:

Square aspect ratio (1:1)
600 x 600 px minimum, 1200 x 1200 px maximum
JPEG only
White background, head 50-69% of frame

The 240 KB cap means JPEG quality must be in the 60-70 range AND dimensions cannot exceed about 800 x 800 px. Smaller dimensions actually help here - a 600 x 600 px photo at quality 80 fits comfortably.

The same cap does not apply to the paper passport photo (which is 51 x 51 mm at 300 DPI, no file size limit). DS-160 is digital-only, separate constraint.

// DS-160-compliant output (square + 240 KB cap)
async function exportForDS160(canvas) {
  // Force square 600x600
  const out = document.createElement('canvas')
  out.width = 600
  out.height = 600
  out.getContext('2d').drawImage(canvas, 0, 0, 600, 600)
  // Tune quality to fit 240 KB
  for (const q of [0.85, 0.80, 0.75, 0.70, 0.65, 0.60]) {
    const blob = await new Promise(r => out.toBlob(r, 'image/jpeg', q))
    if (blob.size <= 240_000) return blob
  }
  throw new Error('Could not fit 240 KB cap')
}

The validated US flow is at the US passport photo tool which produces the DS-160-compatible square JPG plus a print-ready 51 x 51 mm PDF in the same export.

Architecture summary

Three portals, three different constraints, all of which the browser can solve without uploading anything.

The architecture I settled on:

Capture or upload in the browser. No server, no upload.
Face detection with face-api.js (WebAssembly + tiny TF model). Returns landmarks for cropping.
Background segmentation with BRIA RMBG-1.4 (WebAssembly inference). Returns a per-pixel mask.
Country-specific cropping based on each spec (head height, dimensions, ratio).
Background replacement to pure white or country-specific (light grey for German, white for most).
JPEG export with country-specific quality tuning to hit file-size constraints.

Privacy-wise the win is that biometric data (face, segmentation mask) never leaves the device. Practically, the win is that you can run validation against the actual portal constraints before the user even tries to upload, saving them the rejected-application loop.

The full tool is at idphotosnap.com - free, no signup, no watermark, 85+ countries.

FAQ

Q: Why not just use a server for image processing?

For passport photos specifically, the photo contains biometric data (face, expression, distinguishing marks). Many users of these tools are visa applicants from one country applying to another - exactly the scenario where regulators (and users) prefer the photo never reach a third-party server. WebAssembly inference makes this practical.

Q: How accurate is browser-side background segmentation?

BRIA RMBG-1.4 is good enough for hairline accuracy in most lighting conditions. The failure mode is high-contrast hair against a light background - here the segmentation occasionally clips fine strands. We mitigate by running a guided filter post-processing pass on the mask.

Q: What about countries with light grey backgrounds (UK, Germany)?

Same architecture, different output color. The mask defines the background region; replacement is just fillStyle = '#eeeeee' instead of #ffffff for those cases.

Q: Why do countries diverge so much on file size limits?

Most portals were built when JPEG was the only practical format and bandwidth was tight. The 240 KB DS-160 cap predates HTTPS being the default - it is a 2010-era constraint that no one updated as cameras got better. The 20 KB minimum on Sarathi is anti-malware (rejects very small files that might be exploit payloads). Combined, these heuristics are the legacy you have to code around.

Q: Open source?

The validators are not, but the architecture pattern is in the article. BRIA RMBG-1.4 and face-api.js are both open weights. WebAssembly is just WebAssembly.

Why your passport photo keeps getting rejected (it's the file, not the picture)

whitetirocket — Mon, 04 May 2026 04:49:35 +0000

If you've ever uploaded a passport photo to a government portal and gotten a vague "photo rejected" error, the problem usually isn't the photo. It's the file.

I've been running IDPhotoSnap, a free browser-based passport photo tool, for a few months now. The single most common support question is some flavor of "my photo looks fine, why does the portal say it's wrong?"

The answer almost always lives in the file's metadata, not the visible image. Here's the breakdown.

The 8 file-level rejection reasons

1. File size out of range

Most embassy portals enforce strict caps:

US State Department DS-160: 240 KB max
UK passport portal: 50 KB - 10 MB
Schengen visa portals: 240 KB - 6 MB depending on country
India passport seva: 20 KB - 300 KB

A modern phone shoots 4-8 MB by default. The portal rejects before any human sees the picture.

2. Wrong DPI

DPI is metadata. It doesn't change pixel data — it just labels the image as "intended for printing at this density". Phone cameras tag photos at 72 DPI. Embassy print pipelines require 300.

// In a JPEG, DPI lives in the JFIF header (bytes 13-18) or EXIF tag 0x011A.
// Changing it does NOT recompress or resize - just rewrites those bytes.

You can verify in any terminal:

identify -format "%x x %y\n" photo.jpg  # ImageMagick
# Output: 72x72  ← needs to be 300x300

The pixel content is identical. The metadata tag is what trips the validator.

3. Wrong dimensions

Every country uses different size requirements:

Country	Size
US	600×600 px (2×2 inches)
Schengen	35×45 mm
UK	35×45 mm at 600×750 px minimum
India	51×51 mm at 600×600 px
Japan	35×45 mm at 413×531 px

A photo that passes for one country fails for another. There's no universal size.

4. Wrong format (HEIC, WebP, PNG)

iPhones save HEIC by default. Android sometimes saves WebP. Most government portals only accept JPG. About half also reject PNG.

The HEIC → JPG conversion can be done client-side with libheif compiled to WASM:

import { decode } from 'libheif-js'

async function heicToJpeg(file) {
  const buf = await file.arrayBuffer()
  const decoder = new Decoder()
  const data = decoder.decode(new Uint8Array(buf))
  // ... draw onto canvas, export as JPEG with quality 0.92
}

5. Background isn't pure white

Background validators look for RGB(255,255,255) ± a small delta. Common failures:

Off-white walls (255, 250, 245)
Window light gradient across the wall
Soft shadow behind the head

For true compliance, replace the background entirely. ML segmentation models like MODNet (~25 MB ONNX) run in-browser via onnxruntime-web.

6. Compression artifacts

Quality 60% JPEG produces visible block artifacts. Validators sometimes flag low SSIM. Recompress at quality 90-95%, target the size limit by re-trying with smaller pixel dimensions if needed — never below the size threshold.

7. Color profile mismatch

Display-P3 photos from iPhones can fail validators that expect sRGB. Convert before export:

ctx.imageSmoothingEnabled = true
ctx.drawImage(img, 0, 0)
const data = ctx.getImageData(0, 0, w, h)
// canvas defaults to sRGB - the act of drawing converts it

8. Embedded thumbnail mismatch

Obscure but real: some portals compare the EXIF thumbnail to the main image. If they differ (e.g., you cropped the main but the thumbnail is the original), it's flagged as edited. Strip EXIF entirely:

// Re-encoding via canvas removes all EXIF/XMP/IPTC metadata
const clean = canvas.toBlob(blob => ..., 'image/jpeg', 0.95)

Why a browser-only tool makes sense here

All the operations above are pure pixel manipulation. None of them require server compute. None of them require AI in the cloud. Even background replacement runs locally with onnxruntime-web at ~2-5 seconds per image on a mid-range laptop.

Uploading a photo of your face to a third-party service to do work that runs fine in WebAssembly is bad architecture and worse privacy.

If you want to see this approach in action, IDPhotoSnap handles all 8 of these issues for 85+ countries with zero uploads. There's a separate Photo Rejected hub that diagnoses an existing rejected photo and fixes the specific issue, also entirely client-side.

Lesson

When a government portal rejects "a fine-looking photo," 90% of the time it's reading the file's metadata, not the picture. Engineering for this is mostly about being deliberate about what you write into the JPEG header — DPI tag, dimensions, color profile, embedded thumbnails — not about the pixels themselves.

FAQ

Q: Why do passport portals not give specific error messages?
A: They run a chain of validators (size → format → DPI → dimensions → background) and abort on the first failure. Some surface only the last failure code. Many surface nothing useful at all.

Q: Will printing the photo fix DPI?
A: Yes for in-person submission. No for online portals — they read the file metadata, not the print.

Q: Can I just convert HEIC to JPG and call it done?
A: Often yes for size and format checks. But the converter often loses the DPI tag (defaults to 72) and the dimensions stay phone-default, so 50% of the time you also need a resize and a DPI rewrite.

Q: Is server-side processing ever needed for this?
A: Not for 99% of cases. Background removal is the only borderline case (large model file). Everything else fits comfortably in Canvas + a few KB of code.

Building a privacy-first passport photo tool that runs entirely in the browser

whitetirocket — Tue, 28 Apr 2026 04:03:10 +0000

I launched IDPhotoSnap on Product Hunt today. It's a free passport, visa, and ID photo maker for 85+ countries. Here's the technical writeup of why it runs 100% in the browser, what that bought me, and where the tradeoffs were.

Why client-side

The straightforward way to build this product would have been:

User uploads photo → server
Server runs image processing (crop, resize, background)
Server sends back result

This is the architecture every paid competitor uses. It also costs money to run, requires user accounts to manage abuse, and creates a privacy concern: somewhere on a server is a database of passport photos.

Client-side processing flips all three:

Cost: $0 compute. The user's phone does the work.
Abuse model: there's nothing to abuse. There's no server to overload, no API to rate-limit.
Privacy: the photo never leaves the device. This is verifiable — open DevTools and watch the network tab.

What's actually running in the browser

The core processing pipeline:

async function processPhoto(file, countrySpec) {
  const img = await loadImage(file)
  const faceBox = await detectFace(img)
  const cropBox = computeCrop(faceBox, countrySpec)
  const canvas = renderCrop(img, cropBox, countrySpec.dimensions)
  return canvas.toDataURL('image/jpeg', 0.92)
}

Three steps that matter:

1. Face detection uses the FaceDetector API where available (Chrome on Android, recent Safari) and falls back to a small TensorFlow.js model on browsers that don't support it. The fallback adds about 4MB to the initial load but only loads on demand.

2. Crop computation is country-specific. Each country has documented requirements like "face must occupy 70-80% of the frame, vertically centered, eyes at 60% from the bottom." These are encoded as JSON specs:

{
  "country": "US",
  "dimensions": { "width_mm": 51, "height_mm": 51, "dpi": 300 },
  "face": { "min_height_pct": 50, "max_height_pct": 69, "vertical_center_pct": 56 },
  "background": "#FFFFFF",
  "head_position": "centered"
}

Getting these specs right was the actual hard work. Some governments publish them well. Most don't. I ended up cross-referencing consulate PDFs in the local language for about half the countries.

3. Canvas rendering is just drawImage with the computed bounding box, then toDataURL for export. No magic.

Background removal

This was the part where I almost gave up on client-side. Background removal historically meant a U-Net or similar segmentation model — too heavy for the browser.

The answer was the MediaPipe Selfie Segmentation model. It's about 256KB, runs at 30fps on a mid-range phone, and produces a soft alpha mask good enough for passport photo backgrounds. After segmentation, I composite over a white canvas. Done.

What I lost by going client-side

Three real tradeoffs:

No analytics on uploaded photos. Useful for debugging but obviously not viable here.
Initial load is heavier. First visit fetches face detection fallback + segmentation model. Total: ~5MB. After cache, instant.
No batch processing. Can't queue 1000 photos through. But this is a passport photo tool — one photo at a time is the use case.

What I gained

Hosting cost is $0. Just a static site on Vercel.
No GDPR exposure. No user data is collected because none is transmitted.
Genuinely free. Because there's no compute cost, the product can stay free forever without ads, subscriptions, or tier-locking.

On Product Hunt

If you want to see the result, the launch is here: https://www.producthunt.com/products/idphotosnap

The site itself is at https://idphotosnap.com.

FAQ

Q: How does this make money?
It doesn't yet. If traffic grows, I'll add unobtrusive ads. No subscription tier planned.

Q: Why not WebAssembly for face detection?
The FaceDetector API is fast enough on modern phones and the TF.js fallback handles older browsers. WASM would be a reasonable optimization later but isn't blocking anything.

Q: What if I want to verify the photo doesn't leave my device?
Open DevTools → Network tab → upload a photo. You'll see no requests carrying image data.

Q: Can I self-host?
Not open source yet. Possibly in the future after the codebase stabilizes.

Feedback welcome. The hardest thing right now isn't the code, it's getting the country specs right — if you've used the tool for a country and the result was rejected, I want to know.

DEV Community: whitetirocket

I open-sourced passport photo specs for 100 countries (MIT, JSON, public API)

I open-sourced passport photo specs for 100 countries (MIT, JSON, public API)

What is in it

Three ways to use it

1. HTTP API (no clone)

2. NPM-style import

3. Plain JSON in any language

Why I bothered

Notable specs that catch tool builders

Validation methodology

Architecture (in case you are building something similar)

What I want from this

Used in production

Links

Validating Passport Photos for 3 of the Strictest Government Portals (India, China, US)

Validating Passport Photos for 3 of the Strictest Government Portals (India, China, US)

India: Sarathi and Parivahan portals

China: COVA online visa portal

US DS-160: the 240 KB cap

Architecture summary

FAQ

Why your passport photo keeps getting rejected (it's the file, not the picture)

The 8 file-level rejection reasons

1. File size out of range

2. Wrong DPI

3. Wrong dimensions

4. Wrong format (HEIC, WebP, PNG)

5. Background isn't pure white

6. Compression artifacts

7. Color profile mismatch

8. Embedded thumbnail mismatch

Why a browser-only tool makes sense here

Lesson

FAQ

Building a privacy-first passport photo tool that runs entirely in the browser

Why client-side

What's actually running in the browser

Background removal

What I lost by going client-side

What I gained

On Product Hunt

FAQ