API PhotoFig

Les routes API acceptent les clés API générées à partir de Paramètres. Le secret complet n'est affiché qu'une seule fois lors de la création de la clé.

Authorization: Bearer pf_live_...

Utilisez cette route pour vérifier vos identifiants et consulter les limites du forfait, les crédits restants et les outils disponibles.

{
  "accountId": "uuid",
  "workspaceId": "uuid",
  "plan": "pro",
  "apiEnabled": true,
  "credits": {
    "remaining": 1200,
    "periodEndsAt": "2026-08-01T00:00:00Z"
  },
  "limits": {
    "maxFileSizeBytes": 25000000,
    "rateLimitPerHour": 500,
    "concurrentJobs": 5,
    "maxApiKeys": 3
  },
  "tools": ["mask", "ai-bg", "ai-shadows"]
}

Chaque outil accepte une image produit via imageUrl, uploadSessionId ou un envoi multipart. Il n'est pas nécessaire d'appeler d'abord l'outil mask, sauf si vous souhaitez obtenir un détourage transparent.

C'est le parcours le plus simple : envoyez une modification avec imageUrl si l'image source est déjà accessible par URL, ou transmettez le champ image en multipart pour un fichier local. Cette méthode convient lorsqu'un seul outil doit traiter une seule image.

Choisissez cette option pour traiter une image une seule fois, sans avoir à réutiliser le fichier source importé.

curl -X POST https://api.photofig.com/v1/tools/ai-shadows/edit \
  -H "Authorization: Bearer pf_live_..." \
  -F "[email protected]" \
  -F "seed=128742"

Créez une session d'importation lorsque la source est un fichier local volumineux ou lorsque plusieurs outils doivent traiter la même image. Le fichier n'est envoyé qu'une fois vers le stockage ; les demandes suivantes transmettent uniquement l'uploadSessionId obtenu.

Choisissez cette option pour les fichiers volumineux ou lorsque la même image source doit servir à plusieurs outils ou tentatives.

UPLOAD_JSON=$(curl -s -X POST https://api.photofig.com/v1/uploads \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "image/jpeg",
    "filename": "product.jpg",
    "sizeBytes": 1842031
  }')

curl -X PUT "$(echo "$UPLOAD_JSON" | jq -r '.uploadUrl')" \
  -H "Content-Type: image/jpeg" \
  --data-binary @product.jpg

curl -X POST https://api.photofig.com/v1/tools/ai-shadows/edit \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d "{
    \"uploadSessionId\": \"$(echo "$UPLOAD_JSON" | jq -r '.uploadSessionId')\",
    \"parameters\": { \"seed\": 128742 }
  }"

Soumettez les modifications avec imageUrl, uploadSessionId ou le champ multipart image. La réponse renvoie un identifiant de tâche utilisable pour suivre, annuler ou supprimer la tâche et associer les événements webhook.

Arrière-plan IA

Le point de terminaison d'arrière-plan IA fonctionne mieux avec un thème de scène concis : un décor, une surface, un type d'éclairage ou une ambiance en quelques mots. Par exemple warm oak tabletop,minimal white studio, and soft morning kitchen light.

curl -X POST https://api.photofig.com/v1/tools/ai-bg/edit \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://cdn.example.com/product.png",
    "parameters": {
      "theme": "warm oak tabletop",
      "seed": 128742
    }
  }'

Product Shadow

curl -X POST https://api.photofig.com/v1/tools/ai-shadows/edit \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://cdn.example.com/product.png",
    "parameters": { "seed": 128742 }
  }'

Masque

curl -X POST https://api.photofig.com/v1/tools/mask/edit \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://cdn.example.com/product.png",
    "parameters": { "mode": "standard" }
  }'

Répertoriez, consultez, annulez ou supprimez les tâches API. Elles n'apparaissent ni dans les fichiers importés ni dans les créations de l'application. Leur suppression efface également les fichiers associés à l'API.

GET /v1/jobs/{id} renvoie les métadonnées d'état au format JSON. Une fois le traitement terminé, téléchargez l'image depuis resultUrl. Consulter régulièrement l'état est la méthode d'intégration la plus simple ; utilisez les webhooks pour prévenir automatiquement votre backend.

{
  "id": "api_edit_uuid",
  "tool": "ai-shadows",
  "status": "completed",
  "createdAt": "2026-07-15T10:15:00Z",
  "startedAt": "2026-07-15T10:15:04Z",
  "finishedAt": "2026-07-15T10:15:23Z",
  "statusUrl": "https://api.photofig.com/v1/jobs/api_edit_uuid",
  "resultUrl": "https://storage.example.com/signed-result-url",
  "thumbnailUrl": "https://storage.example.com/signed-thumbnail-url",
  "expiresAt": "2026-07-15T11:15:23Z",
  "error": null
}

Les webhooks sont des rappels de PhotoFig vers votre serveur. Enregistrez une URL HTTPS et PhotoFig envoie une demande lorsqu'une tâche d'API se termine, échoue ou est annulée. Cela permet à votre backend de réagir immédiatement au lieu d'interroger GET /v1/jobs/{id} jusqu'à ce que l'état change.

Les événements pris en charge sont webhook.test,job.completed,job.failed, et job.cancelled. Les charges utiles d'événement utilisent le même ID de tâche renvoyé lors de la création de la modification.

{
  "event": "job.completed",
  "eventId": "uuid",
  "createdAt": "2026-07-15T10:15:23Z",
  "data": {
    "id": "api_edit_uuid",
    "tool": "ai-shadows",
    "status": "completed",
    "resultUrl": "https://storage.example.com/signed-result-url",
    "thumbnailUrl": "https://storage.example.com/signed-thumbnail-url"
  }
}

Les réponses d'erreur contiennent un code stable lisible par machine et un message compréhensible. Utilisez le code pour adapter la logique du client.

{
  "code": "invalid_request",
  "message": "imageUrl or uploadSessionId is required"
}

Les tâches API terminées restent visibles via GET /v1/jobs et GET /v1/jobs/{id}. La réponse d'état contient les liens signés resultUrl et thumbnailUrl dès que les résultats sont disponibles.

Les fichiers produits par l'API sont stockés séparément des fichiers importés et des créations de l'application. Ils n'apparaissent pas dans la bibliothèque.

Les enregistrements des tâches API ainsi que leurs fichiers d'entrée, résultats et miniatures sont conservés pendant 1 heure une fois la tâche terminée, échouée ou annulée. Le champ expiresAt indique l'heure de suppression prévue.

Utilisez DELETE /v1/jobs/{id} après avoir téléchargé les résultats dont vous n'avez plus besoin. Cette requête annule si possible le traitement en cours, puis supprime la tâche et ses fichiers avant le nettoyage automatique.