Sample Python Code

These examples use Python 3 and the requests package. Set credentials as environment variables instead of placing real secrets in source code.

export IDPHOTO_API_KEY="your-api-key"
export IDPHOTO_API_SECRET="your-api-secret"

Install the dependency:

python -m pip install requests

Create a final ID photo

import base64
import os

import requests

BASE_URL = "https://api-us.idphotoapp.com"
IMAGE_PATH = "portrait.jpg"

with open(IMAGE_PATH, "rb") as image_file:
    image_base64 = base64.b64encode(image_file.read()).decode("ascii")

response = requests.post(
    f"{BASE_URL}/v2/makeIdPhoto",
    json={
        "apiKey": os.environ["IDPHOTO_API_KEY"],
        "apiSecret": os.environ["IDPHOTO_API_SECRET"],
        "imageBase64": image_base64,
        "specCode": "us-passport",
        "outputFormat": "IMAGE_BASE64",
    },
    timeout=120,
)
response.raise_for_status()
result = response.json()

issues = result.get("issues") or []
if issues:
    print("Review these photo issues:", ", ".join(issues))

encoded_photo = result.get("idPhotoImageBase64")
if not encoded_photo:
    raise RuntimeError("The response did not contain Base64 image data")

with open("id-photo.jpg", "wb") as output_file:
    output_file.write(base64.b64decode(encoded_photo))

print("Created photo:", result["photoUuid"])

Use the EU base URL instead when your account is configured for the EU region.

Watermarked-preview flow

import base64
import os

import requests

BASE_URL = "https://api-us.idphotoapp.com"
AUTH = {
    "apiKey": os.environ["IDPHOTO_API_KEY"],
    "apiSecret": os.environ["IDPHOTO_API_SECRET"],
}

with open("portrait.jpg", "rb") as image_file:
    image_base64 = base64.b64encode(image_file.read()).decode("ascii")

preview_response = requests.post(
    f"{BASE_URL}/v2/makeIdPhotoWatermark",
    json={
        **AUTH,
        "imageBase64": image_base64,
        "specCode": "uk-passport",
        "watermarkText": "Preview",
    },
    timeout=120,
)
preview_response.raise_for_status()
preview = preview_response.json()

photo_uuid = preview["photoUuid"]
print("Preview created:", preview.get("idPhotoUrl"))

# Call this only after the user confirms the preview or completes payment.
final_response = requests.post(
    f"{BASE_URL}/v2/getIdPhotoNoWatermark",
    json={**AUTH, "photoUuid": photo_uuid},
    timeout=120,
)
final_response.raise_for_status()
final_photo = final_response.json()

print("Final photo:", final_photo.get("idPhotoUrl"))

Keep the same region for both calls and store photoUuid on your server.

Handle API and network errors

import requests

try:
    response = requests.post(
        "https://api-us.idphotoapp.com/v2/queryAccountStatus",
        json={
            "apiKey": "your-api-key",
            "apiSecret": "your-api-secret",
        },
        timeout=30,
    )
    response.raise_for_status()
except requests.Timeout:
    print("The request timed out; check its outcome before retrying.")
except requests.HTTPError as error:
    status = error.response.status_code
    detail = error.response.text[:500]
    print(f"API request failed with HTTP {status}: {detail}")
except requests.RequestException as error:
    print(f"Network error: {error}")
else:
    print(response.json())

In production:

• do not log API secrets or complete Base64 payloads;
• limit logged response bodies because they may contain image data;
• validate local file type and size before encoding;
• use an application-level timeout appropriate for image processing; and
• avoid automatically retrying a request when its outcome is uncertain.