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é

POST/api/v1/workflows/{workflow_id}
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')

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')

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"
}

Paramètres de requête

workflow_id

Type: stringRequis

The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.

images

Type: 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.

options

Type: 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_text

Type: 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_images

Type: integer

Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.

= 1

aspect_ratio

Type: 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:9
resolution

Type: string

Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.

= 2K

Valeurs: 2K4K

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.

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.

  1. É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.

  2. É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.

  3. É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.

  4. É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.

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

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

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