How the API works

Global Snap uses a job-based workflow. Your app sends an image and a transformation request. We return a job ID immediately. Your app can either poll the job endpoint or receive a webhook when the result is ready.

1Send image + transform

2Receive queued job

3Poll or wait for webhook

4Render final image

These docs show the public API contract only. Internal prompts, model settings, GPU routing, queue workers, and admin endpoints are intentionally hidden.

Authentication

Use a bearer token with every request.

Authorization: Bearer GLOBALSNAP_API_KEY
Content-Type: application/json

POST/v1/try-on

Create a visual transformation job

Create an asynchronous job for hair color, hairstyle, beard, makeup, or general image-editing flows.

Request body

Parameter	Type	Required	Description
`image`	string	Yes	Base64 data URL. Hosted image URL support can be enabled for approved integrations.
`transform`	string	Yes	The transformation category, for example `hair_color`, `beard`, or `image_edit`.
`style`	string	Yes	A preset or desired result, for example `warm_balayage`.
`webhook`	string	No	Your HTTPS endpoint for completion events.

Examples

cURL

curl https://api.globalsnap.example/v1/try-on \
  -H "Authorization: Bearer $GLOBALSNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "data:image/jpeg;base64,...",
    "transform": "hair_color",
    "style": "warm_balayage",
    "webhook": "https://yourapp.com/webhooks/global-snap"
  }'

Python

import os
import requests

response = requests.post(
    "https://api.globalsnap.example/v1/try-on",
    headers={
        "Authorization": f"Bearer {os.environ['GLOBALSNAP_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "image": "data:image/jpeg;base64,...",
        "transform": "hair_color",
        "style": "warm_balayage",
        "webhook": "https://yourapp.com/webhooks/global-snap",
    },
)

job = response.json()
print(job["id"], job["status"])

JavaScript

const response = await fetch(
  "https://api.globalsnap.example/v1/try-on",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GLOBALSNAP_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      image: "data:image/jpeg;base64,...",
      transform: "hair_color",
      style: "warm_balayage",
      webhook: "https://yourapp.com/webhooks/global-snap",
    }),
  }
);

const job = await response.json();

Response

{
  "id": "job_8f4b2c91",
  "status": "queued",
  "created_at": "2026-05-18T10:30:00Z"
}

GET/v1/jobs/{job_id}

Poll job status

Poll this endpoint until the status becomes completed or failed.

curl https://api.globalsnap.example/v1/jobs/job_8f4b2c91 \
  -H "Authorization: Bearer $GLOBALSNAP_API_KEY"

Completed response

{
  "id": "job_8f4b2c91",
  "status": "completed",
  "result": {
    "image": "https://cdn.globalsnap.example/results/job_8f4b2c91.jpg"
  },
  "created_at": "2026-05-18T10:30:00Z",
  "completed_at": "2026-05-18T10:30:08Z"
}

Webhooks

Add a webhook URL when creating a job. Global Snap sends a compact event when the transformation finishes.

{
  "event": "job.completed",
  "id": "job_8f4b2c91",
  "status": "completed",
  "result": {
    "image": "https://cdn.globalsnap.example/results/job_8f4b2c91.jpg"
  }
}

Transforms

Transform	Example styles	Use case
`hair_color`	warm_balayage, copper_red, ash_blonde	Hair color try-on and salon previews.
`hairstyle`	long_layers, pixie_cut, curly_bob	Haircut and style exploration.
`beard`	light_stubble, full_beard, clean_shave	Men's grooming flows.
`makeup`	natural_glow, glam_evening, soft_lip	Beauty and cosmetics previews.
`image_edit`	editorial, background_clean, product_scene	General app-scale image editing.

Error responses

Status	Code	Meaning
400	`invalid_request`	Missing field, invalid transform, or unsupported image format.
401	`unauthorized`	Missing or invalid API key.
402	`quota_exceeded`	Plan quota or billing limit reached.
422	`image_unprocessable`	The image cannot be processed for the requested transformation.
503	`temporarily_unavailable`	The queue is temporarily unavailable. Retry with backoff.

Global Snap API