Fonctionnalité · Workflows
API Workflows un appel, un preset
En une phrase
L'API workflows de Photta applique des templates de scènes prêts à l'emploi sur vos images de produits. Récupérez le catalogue, remplissez les emplacements d'images et les options du workflow, faites un POST, puis effectuez le polling de chaque élément renvoyé jusqu'à son achèvement.
- Délai typique: 20–60 sec / image
- 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é
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/workflows/jewelry-studio-shot \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/workflows/jewelry-studio-shot", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/workflows/jewelry-studio-shot",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
},
)
data = res.json()["data"] # data["id"], data["status"]En un coup d'œil
En un coup d'œil
- Endpoint
- POST /api/v1/workflows/{workflow_id}
- Authentification
- Clé API Bearer
- Traitement
- Asynchrone — interrogez l'endpoint de statut par polling
- Délai typique
- 20–60 sec / image
- 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
Requête et réponse
Requête
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/workflows/jewelry-studio-shot \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/workflows/jewelry-studio-shot", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/workflows/jewelry-studio-shot",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
},
)
data = res.json()["data"] # data["id"], data["status"]202 Accepted / Terminé
{
"data": {
"items": [
{
"id": "wfl_1f7c03a9e5b2486dd90c4b17ae62f508",
"workflow_id": "jewelry-studio-shot",
"status": "processing",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 4,
"created_at": "2026-08-03T10:20:00Z"
},
{
"id": "wfl_8b2d64f0a1c9573ee4082d6cb95a3f17",
"workflow_id": "jewelry-studio-shot",
"status": "processing",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 4,
"created_at": "2026-08-03T10:20:00Z"
}
],
"workflow_id": "jewelry-studio-shot",
"workflow_version": 1,
"credits_used": 8
},
"request_id": "req_wfl002"
}{
"data": {
"id": "wfl_1f7c03a9e5b2486dd90c4b17ae62f508",
"workflow_id": "jewelry-studio-shot",
"status": "completed",
"output_url": "https://cdn.photta.app/generated/wfl_1f7c03a9e5b2486dd90c4b17ae62f508.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/wfl_1f7c03a9e5b2486dd90c4b17ae62f508-thumb.jpg",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 4,
"created_at": "2026-08-03T10:20:00Z",
"completed_at": "2026-08-03T10:20:41Z",
"error_code": null,
"error_message": null
},
"request_id": "req_wfl003"
}Paramètres de requête
workflow_idType: stringRequis
The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.
imagesType: objectRequis
Map of image slot id → array of images (https URL or base64 data URI). Slot ids, required flags, and min/max image counts come from the workflow's image_slots in the catalog. Missing entirely, missing a required slot, using an unknown slot, or exceeding a slot's max_images returns 400.
optionsType: object
Map of option id → choice id, both from the workflow's options in the catalog. Omitted options use their default_choice. Unknown option ids or choice ids return 400, as does sending an option that a filled image slot replaces (see replaces_options).
user_textType: string
Free-text styling/framing request (e.g. "hero shot, slightly angled"). Max 500 characters — excess is silently truncated. It never overrides product fidelity: the product always stays true to your images.
num_imagesType: integer
Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.
= 1
aspect_ratioType: string
Output aspect ratio. Defaults to the workflow's default_aspect_ratio from the catalog (3:4 for every current workflow).
= 3:4
Valeurs:3:41:14:39:1616:9resolutionType: string
Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.
= 2K
Valeurs:2K4K
Erreurs
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_error - An internal server error occurred. Retry later.
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.
Récupérez le catalogue, remplissez les emplacements, exécutez
Listez les workflows, remplissez les emplacements déclarés, soumettez, effectuez le polling de chaque élément, téléchargez.
Étape 1
Générer une clé d'API
Les workflows utilisent les mêmes identifiants et le même solde de crédits que toutes les autres fonctionnalités de Photta.
Étape 2
Lister le catalogue de workflows
GET `/api/v1/workflows` renvoie les 53 templates répartis sur 7 catégories, chacun déclarant ses propres emplacements d'images, énumérations d'options et ratio d'aspect par défaut. Filtrez avec `category` — une catégorie inconnue renvoie une 400 plutôt que d'être ignorée.
Étape 3
Exécuter le POST
POST `/api/v1/workflows/:workflow_id` avec `images` (slot id vers images) et `options` (option id vers choice id), tous deux extraits de l'entrée du catalogue. `user_text` accepte une requête de style en texte libre, et `num_images` génère 1 à 4 images en un seul appel.
Étape 4
Effectuer le polling de chaque élément
La réponse 202 contient un élément par image demandée. Effectuez un GET sur `/api/v1/workflows/generations/:id` toutes les 3 secondes pour chaque id jusqu'à ce que `data.status` soit `completed` ou `failed` ; le délai d'exécution typique est de 20 à 60 secondes par image.
Étape 5
Télécharger et persister
Chaque élément terminé contient son propre `output_url`. Les éléments se terminent indépendamment, ce qui vous permet de publier le premier pendant que les autres sont encore en cours de rendu.
Le même endpoint en Node.js, Python et cURL
Node.js
API Workflows en Node.js
Appelez aPI Workflows de Photta depuis un backend Node.js avec fetch natif. Aucun SDK requis : stockez votre clé, soumettez le job, récupérez le résultat par polling.
LirePython
API Workflows en Python
Appelez aPI Workflows de Photta en Python avec la bibliothèque requests. Un wrapper de trente lignes, compatible asynchrone via httpx, fonctionnant dans Django, FastAPI et Celery.
LirecURL
API Workflows avec cURL
Appelez aPI Workflows de Photta directement depuis le shell avec cURL. Soumettez, effectuez le polling, téléchargez — chaque extrait s'associe à jq pour vos pipelines scriptés.
Lire
Questions posées par les développeurs avant d'exécuter des workflows
Qu'est-ce que l'API workflows ?
Un catalogue de templates de scènes prêts à l'emploi que vous appliquez à vos propres photographies de produits. Au lieu d'élaborer un prompt, vous choisissez un workflow et renseignez les emplacements d'images et les options qu'il déclare.
Combien coûte l'exécution d'un workflow ?
4 crédits par image en 2K et 5 par image en 4K, multipliés par `num_images`. Le catalogue indique le prix en direct pour chaque workflow — lisez-le directement là-bas au lieu de faire des suppositions.
Comment trouver un identifiant de workflow ?
GET `/api/v1/workflows`. Chaque entrée comprend son id, sa catégorie, ses emplacements d'images et ses options. Filtrez la liste avec `category` : `jewelry`, `product`, `shoe`, `cosmetics`, `food`, `bag` ou `watch`.
Que contiennent images et options ?
`images` mappe un slot id de l'entrée du catalogue à un tableau d'images, sous forme d'URLs https ou de data URIs en base64. `options` mappe un option id à l'un des choice ids de cette option. Ces deux structures proviennent du catalogue, c'est pourquoi l'intégration reste compatible lors de l'ajout de nouveaux workflows.
Combien d'images une exécution peut-elle produire ?
`num_images` accepte de 1 à 4. Chaque image est générée indépendamment et reçoit son propre item id dans la réponse, ce qui permet à l'une d'échouer sans faire échouer les autres.
Comment effectuer le polling pour obtenir les résultats ?
Interrogez chaque élément séparément : GET `/api/v1/workflows/generations/:id` toutes les 3 secondes. GET `/api/v1/workflows/generations/list` fournit une vue paginée filtrée par `workflow_id` ou `status`.
Fonctionnalités associées
Fonctionnalités
API de try-on virtuel pour les vêtements
API REST qui positionne des vêtements sur des mannequins générés par IA. Traitement asynchrone, génération en 1.5–4 minutes, 5 crédits en 2K, 6 en 4K. Exemples en cURL, Node.js et Python.
Voir l'endpointFonctionnalités
API de try-on de bijoux pour colliers, bagues, bracelets et boucles d'oreilles
Positionnez colliers, bagues, bracelets et boucles d'oreilles sur des modèles IA via REST. 5 crédits en 2K, mannequins gros plan intégrés, rendu gérant les reflets d'après la documentation de Photta.
Voir l'endpointDévelopper
Créer un service de photographie de produits par IA
Le guide pour les fondateurs souhaitant revendre l'API de try-on virtuel de Photta sous forme de SaaS en marque blanche : clés par tenant, distribution par lots, facturation au credit, réalité des SLA.
Voir l'endpointComparer
Photta vs Ayna — API pour développeurs ou studio orienté Shopify
Photta vs Ayna : trois endpoints REST face à un studio orienté Shopify + API. Chacun a ses atouts. Données extraites de chaque site le 2026-04-19.
Voir l'endpointDémarrage rapide
Première image Photta en moins de cinq minutes.
Inscrivez-vous, générez une clé d'API, lancez votre premier appel cURL, effectuez le polling jusqu'à la complétion, persistez le résultat. Cinq étapes documentées de bout en bout.
Voir l'endpointRéférence
Erreurs de l’API Photta
La liste complète des types d’erreurs de l’API Photta avec leurs codes de statut, la structure du corps d’erreur et les échecs pouvant être réessayés.
Voir l'endpointRéférence
Rate limits de l'API Photta
La rate limit de l'API Photta, sa fenêtre, l'en-tête Retry-After, l'intervalle de polling et les plafonds de simultanéité par forfait, tels que documentés dans l'API.
Voir l'endpoint
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.
- 20–60 sec / image
- 4 crédits en 2K · 5 crédits en 4K
- asynchrone, polling
- 600 requêtes/min
- Clé Bearer