cURL · Ghost mannequin API

Ghost mannequin API dengan cURL

Ringkasan singkat

Ekspor PHOTTA_API_KEY, lakukan POST ke https://api.photta.app/api/v1/api/v1/ghost-mannequin dengan body JSON yang terdokumentasi, tangkap ID pembuatan, lalu buat loop GET pada /api/v1/ghost-mannequin/{id} setiap 3 detik hingga data.status bernilai completed. Padukan dengan jq untuk mengekstrak URL output.

  • Waktu umum: 1.5–4 min
  • Credits: 4 credits pada 2K · 5 credits pada 4K
  • Pemrosesan: async, polling
  • Batasan: 600 requests/min
  • Autentikasi: Bearer key

Setiap angka di halaman ini bersumber dari dokumentasi API Photta · diperiksa

POST/api/v1/ghost-mannequin
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
  "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
  "image_side": "front",
  "angle": "side",
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, cream interior lining",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

# $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/ghost-mannequin/$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'

Sekilas

Sekilas

Endpoint
POST /api/v1/ghost-mannequin
Autentikasi
API key Bearer
Pemrosesan
Asinkron — lakukan polling ke endpoint status
Waktu umum
1.5–4 min
Credits
4 credits pada 2K · 5 credits pada 4K
Rasio aspek
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Batas input
Hingga 10 MB per gambar; JPEG, PNG, WebP
Idempoten
Tidak

Cara kerja

Lima langkah shell, tanpa dependensi apa pun selain curl dan jq.

  1. Langkah 1

    Daftar dan buat kunci

    Buka ai.photta.app, masuk ke tab Developers, lalu klik Generate API key. Kunci live diawali dengan `photta_live_`.

  2. Langkah 2

    Ekspor kuncinya

    Tambahkan `export PHOTTA_API_KEY="photta_live_xxx"` di profil shell Anda atau file `.envrc` agar setiap pemanggilan curl berikutnya dapat menggunakannya secara otomatis.

    curl --version   # macOS, Linux, WSL and Windows 10+ ship it
    export PHOTTA_API_KEY="photta_live_xxxxx"
  3. Langkah 3

    Kunci base URL

    `export PHOTTA_BASE_URL="https://api.photta.app/api/v1"` menjaga perintah curl tetap singkat.

    export PHOTTA_BASE_URL="https://api.photta.app/api/v1"
    export AUTH_HEADER="Authorization: Bearer $PHOTTA_API_KEY"
  4. Langkah 4

    Kirim dan lakukan polling

    Lakukan POST ke `$PHOTTA_BASE_URL/api/v1/ghost-mannequin` untuk mendapatkan ID, lalu lakukan loop `curl $PHOTTA_BASE_URL/api/v1/ghost-mannequin/{id}` setiap 3 detik. Teruskan respons ke jq menggunakan pipe untuk mengekstrak `.data.status` secara rapi.

    RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \
      -H "Authorization: Bearer $PHOTTA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
      "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
      "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
      "image_side": "front",
      "angle": "side",
      "style": "3d",
      "background_color": "white",
      "resolution": "2K",
      "aspect_ratio": "3:4",
      "user_instruction": "closed front, cream interior lining",
      "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
    }')
    ID=$(echo "$RESPONSE" | jq -r '.data.id')
    
    # $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/ghost-mannequin/$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'
  5. Langkah 5

    Simpan hasilnya

    Saat job selesai, ambil `.data.output_url` menggunakan jq dan jalankan `curl -o` untuk menyimpan bytes ke penyimpanan lokal — siap untuk tahap pipeline Anda berikutnya.

Error

400invalid_request_error
The request is malformed or contains invalid parameters.
401authentication_error
The API key is missing, invalid, or expired.
402insufficient_credits_error
Your account does not have enough credits.
404not_found_error
The requested resource does not exist.
409conflict_error
The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error
Too many requests. Slow down and retry.Retry-After: 30
500api_error
An internal server error occurred. Retry later.
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

Batasan

  • 600 request per menit per API key (Fixed window; batasannya sama di setiap paket)
  • Respons 429 menyertakan Retry-After: 30 detik
  • Hingga 10 MB per gambar
  • Format: JPEG, PNG, WebP
  • Batch konkuren per paket: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Hanya polling — API tidak mengirim webhook.

Mengapa cURL masih menjadi cara tercepat untuk memverifikasi API

  • Tanpa instalasi — cURL sudah terpasang di setiap OS utama
  • Cocok dipadukan dengan jq untuk scripted pipeline (CI, cron, shell hooks)
  • Cara tercepat untuk melakukan smoke test pada endpoint sebelum mengintegrasikannya ke kode
  • Setiap perintah di halaman ini dapat ditempelkan ke shell POSIX apa pun

Hal yang tidak dilakukannya

  • Polling loop memblokir terminal — beralihlah ke Node atau Python untuk parallel worker
  • Polling adalah satu-satunya sinyal penyelesaian; API tidak mengirimkan webhook
  • Pengguna Command Prompt Windows disarankan menggunakan WSL atau curl.exe milik PowerShell

Pertanyaan umum developer

Apakah ada CLI tool untuk Photta?

Belum ada — tetapi cURL ditambah skrip bash wrapper sepanjang lima belas baris sudah mencakup sebagian besar kebutuhan. Dokumentasi memprioritaskan contoh berbasis cURL karena setiap bahasa dapat menjalankan subprocess, dan shell adalah standar umum di pipeline CI.

Apakah saya memerlukan jq untuk menggunakan API ini?

Tidak wajib — tetapi scripted pipeline jauh lebih mudah menggunakannya. jq memungkinkan Anda mengekstrak `.data.id`, `.data.status`, dan `.data.output_url` dari respons JSON tanpa perlu melakukan parsing manual. Pasang dengan `brew install jq` di macOS atau `apt install jq` di Debian/Ubuntu.

Bagaimana cara melakukan autentikasi dengan curl?

Tambahkan `-H "Authorization: Bearer $PHOTTA_API_KEY"` pada setiap request. Simpan key di environment variable, jangan pernah menuliskannya langsung di skrip yang Anda commit. `curl --oauth2-bearer` juga berfungsi, tetapi bentuk header eksplisit lebih jelas di dokumentasi dan log.

Bisakah saya menggunakan skrip berbasis curl di production?

Untuk backfill batch ad-hoc dan cron job, ya — ribuan tim menjalankan backfill katalog dengan cara ini. Untuk aplikasi jangka panjang, bahasa pemrograman yang matang biasanya lebih baik karena Anda mendapatkan penanganan error, retry, dan observabilitas yang tepat. Contoh curl di halaman ini tetap akurat bahkan setelah Anda mem-portingnya ke Node atau Python; struktur request-nya tetap sama.

Bagaimana cara melakukan polling dari loop bash?

Gunakan `for i in $(seq 1 120); do … ; sleep 3; done` dengan pemeriksaan status di dalam loop body. Keluar dari loop saat `.data.status` bernilai `completed` atau `failed`. Contoh kode di halaman ini menunjukkan pola yang tepat, termasuk batas atas tetap agar job yang macet tidak menggantung skrip selamanya.

Bagaimana cara membaca respons error di curl?

Gunakan `curl -w "\n%{http_code}"` untuk mengambil status code HTTP bersamaan dengan body JSON. Buat percabangan berdasarkan status: 402 untuk credits yang tidak mencukupi, 429 untuk rate limit (ikuti nilai Retry-After), 5xx untuk error server sementara. Body error selalu memiliki field `error.code` dan `error.message`.

Coba API dalam lima menit

Buat Photta API key, tempel cuplikan cURL di atas, dan Anda akan mendapatkan gambar on-model pertama sebelum kopi selesai diseduh.

  • 1.5–4 min
  • 4 credits pada 2K · 5 credits pada 4K
  • async, polling
  • 600 requests/min
  • Bearer key