Quickstart

First Photta image in under five minutes.

In one sentence

Sign up at ai.photta.app, click Generate API key, export it as PHOTTA_API_KEY, POST to /api/v1/tryon/apparel and poll the returned generation ID every 3 seconds until status flips to completed — typically within 1.5 to 4 minutes.

Get an API keyRead the docs
  • Authentication: Bearer key
  • Processing: async, polling
  • Limits: 600 requests/min

Every figure on this page comes from the Photta API docs · checked 

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

How it works

Five commands from zero to first image

Paste them into a terminal in order. Every snippet is self-contained and uses only curl + jq.

  1. Step 1

    Generate an API key

    Sign up at ai.photta.app and open the Developers dashboard. Click Generate API key — live keys start with photta_live_. Export it so the rest of the walkthrough can read it from your shell.

    # https://ai.photta.app → Developers → Generate API key
export PHOTTA_API_KEY="photta_live_xxxxx"
export PHOTTA_BASE_URL="https://api.photta.app/api/v1"

  2. Step 2

    POST your first try-on

    Hit /api/v1/tryon/apparel with a product image URL and a mannequin ID. The API answers 202 Accepted immediately and returns a generation ID in data.id.

    RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

  3. Step 3

    Poll until it completes

    GET /api/v1/tryon/apparel/:id every 3 seconds. Typical completion is 1.5–4 minutes. Put an upper bound on attempts so a stuck job can't hang your script forever.

    # $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed".
for i in $(seq 1 120); do
  RESULT=$(curl -s "https://api.photta.app/api/v1/tryon/apparel/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && echo "generation failed" && exit 1
  sleep 3
done
echo "$RESULT" | jq -r '.data.output_url'

  4. Step 4

    Persist the output

    When status flips to completed, data.output_url holds the rendered image. Download the bytes into your own storage so your product doesn't depend on Photta's CDN for rendering.

    OUTPUT_URL=$(echo "$RESULT" | jq -r '.data.output_url')
curl -sO "$OUTPUT_URL"
echo "Saved $(basename "$OUTPUT_URL")"

  5. Step 5

    Handle the failure modes honestly

    Branch on the HTTP status code: 402 for insufficient credits, 429 for rate limits (honour Retry-After), 5xx for transient server errors. Every error body carries a machine-readable error.code you can act on.

    case "$STATUS_CODE" in
  402) echo "insufficient_credits_error — top up before retrying" ;;
  429) echo "rate_limit_error — wait the Retry-After seconds (30 by default)" ;;
  4??) echo "$BODY" | jq '.error.type, .error.message' ;;
  5??) echo "api_error — retry with backoff" ;;
esac

Questions developers ask

Questions about getting started

How long does the quickstart take?

Five minutes for the signup + key generation + first cURL. The generation itself takes 1.5 to 4 minutes, so plan on ten minutes wall-clock before you see your first on-model image.

Do I need a credit card to try it?

New accounts ship with trial credits you can spend before paying. When you're ready to go to production, subscribe to a plan for a higher monthly credit balance and faster rate limits.

Which endpoint should I try first?

Apparel try-on (/api/v1/tryon/apparel) — it's the most widely used, the documentation is the most complete, and it covers the async + polling pattern every other Photta endpoint reuses. Once you're comfortable there, jewelry and ghost mannequin work the same way.

Can I run it from the browser?

No. Your API key must stay server-side — shipping it to a browser leaks it to every visitor. Route calls through a thin proxy on your own backend (Next.js route handler, Express, Flask, Lambda) and let the browser talk to your proxy instead.

Related pages

Every figure on this page comes from the Photta API docs · checked

You're five minutes away from your first image

Get an API keyExplore the API
  • Bearer key
  • async, polling
  • 600 requests/min