cURL · API mannequin fantôme

API mannequin fantôme avec cURL

En une phrase

Exportez PHOTTA_API_KEY, envoyez un POST à https://api.photta.app/api/v1/api/v1/ghost-mannequin avec le corps JSON documenté, capturez l'ID de génération, puis effectuez une boucle de GET sur /api/v1/ghost-mannequin/{id} toutes les 3 secondes jusqu'à ce que data.status soit completed. Associez avec jq pour extraire l'URL de sortie.

  • Délai typique: 1.5–4 min
  • Crédits: 4 crédits en 2K · 5 crédits en 4K
  • Traitement: asynchrone, polling
  • Limites: 600 requêtes/min
  • Authentification: Clé Bearer

Chaque chiffre sur cette page provient de la documentation de l'API Photta · vérifié

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'

En un coup d'œil

En un coup d'œil

Endpoint
POST /api/v1/ghost-mannequin
Authentification
Clé API Bearer
Traitement
Asynchrone — interrogez l'endpoint de statut par polling
Délai typique
1.5–4 min
Crédits
4 crédits en 2K · 5 crédits en 4K
Rapports d'aspect
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limites d'entrée
Jusqu'à 10 Mo par image ; JPEG, PNG, WebP
Idempotent
Non

Comment ça fonctionne

Cinq étapes dans le shell, zéro dépendance au-delà de curl et jq.

  1. Étape 1

    Inscrivez-vous et générez une clé

    Rendez-vous sur ai.photta.app, ouvrez l'onglet Developers, cliquez sur Generate API key. Les clés de production commencent par `photta_live_`.

  2. Étape 2

    Exporter la clé

    Ajoutez `export PHOTTA_API_KEY="photta_live_xxx"` dans votre profil shell ou dans un fichier `.envrc` afin que chaque appel curl ultérieur la récupère automatiquement.

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

    Définir l'URL de base

    `export PHOTTA_BASE_URL="https://api.photta.app/api/v1"` permet de garder les commandes curl concises.

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

    Soumettre et effectuer le polling

    Envoyez un POST à `$PHOTTA_BASE_URL/api/v1/ghost-mannequin` pour obtenir un ID, puis bouclez avec `curl $PHOTTA_BASE_URL/api/v1/ghost-mannequin/{id}` toutes les 3 secondes. Passez la réponse dans jq pour extraire proprement `.data.status`.

    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. Étape 5

    Persister le résultat

    Quand le job est terminé, extrayez `.data.output_url` avec jq et récupérez les octets avec `curl -o` vers le stockage local — prêt pour l'étape suivante de votre pipeline.

Erreurs

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

Limites

  • 600 requêtes par minute par clé API (Fenêtre fixe ; la limite est identique sur tous les forfaits)
  • Une 429 renvoie Retry-After: 30 secondes
  • Jusqu'à 10 Mo par image
  • Formats: JPEG, PNG, WebP
  • Lots simultanés par forfait: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Polling uniquement — l'API n'envoie aucun webhook.

Pourquoi cURL reste le moyen le plus rapide de vérifier une API

  • Zéro installation — cURL est fourni par défaut avec tous les OS majeurs
  • S'associe à jq pour les pipelines scriptés (CI, cron, hooks shell)
  • Le moyen le plus rapide de smoke-tester un endpoint avant de l'intégrer dans le code
  • Chaque commande de cette page se colle directement dans n'importe quel shell POSIX

Ce qu'il ne fait pas

  • La boucle de polling bloque le terminal — passez à Node ou Python pour des workers parallèles
  • Le polling est le seul signal de complétion ; l'API n'envoie pas de webhooks
  • Les utilisateurs de l'invite de commandes Windows doivent utiliser WSL ou le curl.exe de PowerShell

Questions fréquentes des développeurs

Existe-t-il un outil CLI Photta ?

Pas encore — mais cURL associé à un wrapper bash de quinze lignes couvre la majorité des besoins. La documentation privilégie les exemples cURL d'abord car chaque langage peut exécuter un sous-processus, et le shell est le dénominateur commun dans les pipelines CI.

Ai-je besoin de jq pour utiliser l'API ?

Pas obligatoirement — mais les pipelines scriptés sont bien plus simples avec. jq vous permet d'extraire `.data.id`, `.data.status` et `.data.output_url` de la réponse JSON sans la parser à la main. Installez-le avec `brew install jq` sur macOS ou `apt install jq` sur Debian/Ubuntu.

Comment s'authentifier avec curl ?

Ajoutez `-H "Authorization: Bearer $PHOTTA_API_KEY"` à chaque requête. Conservez la clé dans une variable d'environnement, ne l'insérez jamais en dur dans un script versionné. `curl --oauth2-bearer` fonctionne aussi, mais la forme avec header explicite est plus lisible dans la documentation et les logs.

Puis-je utiliser des scripts basés sur curl en production ?

Pour des rattrapages par lots ponctuels et des tâches cron, oui — des milliers d'équipes livrent des backfills de catalogue de cette façon. Pour une application pérenne, un vrai langage est généralement préférable pour bénéficier d'une gestion propre des erreurs, des retries et de l'observabilité. Les exemples curl de cette page restent valables même après avoir basculé vers Node ou Python ; la structure de la requête est identique.

Comment effectuer le polling depuis une boucle bash ?

Utilisez `for i in $(seq 1 120); do … ; sleep 3; done` en plaçant la vérification du statut dans le corps de la boucle. Interrompez dès que `.data.status` vaut `completed` ou `failed`. L'exemple de code sur cette page montre le pattern exact, y compris une limite supérieure stricte pour éviter qu'un job bloqué n'immobilise le script indéfiniment.

Comment lire les réponses d'erreur avec curl ?

Utilisez `curl -w "\n%{http_code}"` pour capturer le code de statut HTTP aux côtés du corps JSON. Effectuez vos branchements sur le statut : 402 pour des credits insuffisants, 429 pour le rate limit (respectez la valeur de Retry-After), 5xx pour les erreurs serveur temporaires. Le corps de l'erreur contient toujours les champs `error.code` et `error.message`.

Pages associées

Chaque chiffre sur cette page provient de la documentation de l'API Photta · vérifié

Testez l'API en cinq minutes

Générez une clé d'API Photta, collez le snippet cURL ci-dessus, et vous obtiendrez votre première photo portée sur modèle avant même que le café ait fini de couler.

  • 1.5–4 min
  • 4 crédits en 2K · 5 crédits en 4K
  • asynchrone, polling
  • 600 requêtes/min
  • Clé Bearer