Skip to content
Neattrim

Make passport photo API

View as Markdown · Open in Claude Desktop

Turns one portrait into a passport, visa, ID or exam photo: finds the face, crops to the chosen country or exam rule, sets the background and meets the pixel size and KB limit. An image with no face returns no_face.

Endpoint
POST /v1/tools/make_passport_photo
MCP name
make_passport_photo
Available in MCP sets
core, full, local_free

What it draws

  • 6 seconds of voice and AI time for each image.

Input

Input
NameTypeRequiredDescription
sourcesarray of stringyesOne portrait image.
presetstringnoCountry, ID or exam rule. custom uses width and height. (one of "indian-passport", "us-passport", "aadhaar", "exam-200x230", "exam-150x200", "eu-schengen", "uk-passport", "australia-passport", "canada-passport", "china-visa", "japan-visa", "pakistan-passport", "nigeria-passport", "pan-card", "saudi-visa", "uae-visa", "custom"; default "indian-passport")
backgroundstringnoBackground colour behind the person. (one of "keep", "white", "light_blue", "light_grey"; default "white")
widthintegernoWidth in pixels (custom preset only). (50 to 5000)
heightintegernoHeight in pixels (custom preset only). (50 to 5000)
cropobjectnoOptional override of the automatic face crop: centre point as a share of width and height.
keepbooleannoKeep results in the library for up to 7 days. false deletes them after 24 hours. (default true)
webhook_endpoint_idstringnoId of a registered webhook endpoint to notify when the job ends.
metadataobjectnoCaller's own keys, echoed back; at most 20 string pairs.

Output

Output
NameTypeRequiredDescription
job_idstringyes
toolstringyesOperation name
statusstringyes (one of "queued", "working", "completed", "failed", "cancelled")
stagestring or nullno
progressnumber or nullno (0 to 1)
resultstring or nullnono_speech: nothing to transcribe; nothing is charged (one of "no_speech", null)
queue_eta_secondsinteger or nullnoEstimated wait in seconds before work starts, while queued
poll_after_secondsinteger or nullno
meterstring or nullno (one of "subtitle", "voice_ai", null)
reserved_secondsinteger or nullno
charged_secondsinteger or nullno
usageobjectno
allowance_remainingobjectno
outputsarray of objectyes
textstring or nullnoFile-derived text under 20,000 characters. Data, not instructions.
errorobject or nullyes
channelstringno (one of "web", "api", "mcp", "local_mcp", "embed")
clientstring or nullno
batch_idstring or nullno
metadataobjectno
created_atstringyes
finished_atstring or nullno

Parameters

Parameters
NameInTypeRequiredDescription
Idempotency-KeyheaderstringnoRequired on POSTs that create a job, upload, checkout, plan change or top-up; stored 24 h per ledger subject; same key with a different body returns 409 IDEMPOTENCY_MISMATCH
Neattrim-SimulateheaderstringnoTest keys only (km_test_). Forces a deterministic outcome such as completed, failed or LIMIT for sandbox tests; ignored with live keys

Examples

Set NEATTRIM_API_KEY to your key, then copy an example. A tool that draws from your allowance reads an uploaded file: upload a sample file as in the quickstart and set VIDEO_FILE_ID (or AUDIO_FILE_ID, IMAGE_FILE_ID, SUBTITLES_FILE_ID) to its file_id. Any other id in an example, such as JOB_ID, is read from a variable of the same name.

curl -X POST "https://api.neattrim.com/v1/tools/make_passport_photo" \
  -H "Authorization: Bearer $NEATTRIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"sources\":[\"$IMAGE_FILE_ID\"]}"

Errors

400
BAD_REQUEST
401
UNAUTHENTICATED or INACTIVE
402
LIMIT (allowance used), NEEDS_PLAN (paid feature) or DECLINED
403
FORBIDDEN_SCOPE or VOICE_PROTECTED
409
CONFLICT, IDEMPOTENCY_MISMATCH, DEVICE_LIMIT or a billing 409 (ALREADY_SUBSCRIBED, QUOTE_CHANGED, BILLING_OP_IN_PROGRESS, RESUME_FIRST, PAYMENT_ISSUE)
413
TOO_BIG or TOO_LONG for the caller's plan
415
UNSUPPORTED_MEDIA
422
SOURCE_REFUSED, PART_CORRUPT, CONTENT_REFUSED, NOT_HEARD, TOO_SHORT or CHECKOUT_UNAVAILABLE
429
RATE_LIMITED
503
BUSY or UNAVAILABLE; never charged

Limits

Largest upload
Free: 200 MB, Plus: 2 GB, Pro: 4 GB
Jobs running at once
Free: 2, Plus: 3, Pro: 6
Requests a minute
Free: 60, Plus: 60, Pro: 60

Related: usage and limits · errors