Créations

Décrivez ce que vous voulez voir, récupérez une image. Le fichier est hébergé sur media.kreatoai.com et se publie directement avec POST /v1/posts, sans passer par /v1/media.

Kreatoai ne produit pas de vidéo. Une vidéo faite avec l'outil de votre choix se publie comme n'importe quel fichier : envoyez-la avec /v1/media, puis passez l'adresse obtenue à POST /v1/posts.

La création est asynchrone : l'appel répond 202 immédiatement, puis vous interrogez son état, ou vous laissez un webhook vous prévenir. Comptez une trentaine de secondes.

Endpoints

POST

/v1/generations

Lancer une création

GET

/v1/generations/:id

État et résultat

GET

/v1/generations

Créations récentes + solde

DELETE

/v1/generations/:id

Retirer une création de la liste

Scope requis : generations:write pour créer, lire et supprimer. Un abonnement en cours est nécessaire.

Lancer une création

Champ	Obligatoire	Description
`prompt`	oui	Ce que doit montrer l’image. 3 à 1800 caractères
`aspectRatio`	non	`9:16` (défaut), `1:1` ou `16:9`
`type`	non	`image`, la seule valeur acceptée (par défaut)

curl -X POST https://api.kreatoai.com/v1/generations \
  -H "x-api-key: sk-kre-v1-votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Un plat qui sort du four, vapeur, lumière chaude, gros plan",
    "aspectRatio": "9:16"
  }'

// 202 Accepted
{
  "id": "9f1c8b2e-4a7d-4c31-9e05-6b2f8a1d3c47",
  "type": "image",
  "status": "pending",
  "prompt": "Un plat qui sort du four, vapeur, lumière chaude, gros plan",
  "aspectRatio": "9:16",
  "durationSec": null,
  "sourceUrls": [],
  "mediaUrl": null,
  "mimeType": null,
  "error": null,
  "creditsCost": 2,
  "createdAt": "2026-09-26T14:22:10.000Z",
  "completedAt": null
}

Suivre son avancement

Deux façons, au choix. La plus économique : abonnez un endpoint webhook et attendez generation.completed ou generation.failed: le corps de l'événement est exactement l'objet ci-dessous. Sinon, interrogez l'état toutes les dix secondes :

GET /v1/generations/9f1c8b2e-4a7d-4c31-9e05-6b2f8a1d3c47

// 200 OK
{
  "id": "9f1c8b2e-4a7d-4c31-9e05-6b2f8a1d3c47",
  "type": "image",
  "status": "completed",
  "mediaUrl": "https://media.kreatoai.com/generation-image-1788….jpg",
  "mimeType": "image/jpeg",
  "error": null,
  "creditsCost": 2,
  "completedAt": "2026-09-26T14:22:24.000Z"
}

status	Signification
`pending`	Acceptée, pas encore commencée
`processing`	En cours de production
`completed`	`mediaUrl` est prêt à être utilisé
`failed`	`error` porte un texte affichable tel quel. Les crédits ont été rendus

Publier le résultat

mediaUrl se passe directement dans mediaUrls : inutile de l'ingérer avec /v1/media, le fichier est déjà chez nous.

curl -X POST https://api.kreatoai.com/v1/posts \
  -H "x-api-key: sk-kre-v1-votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": ["instagram", "facebook"],
    "content": "Trois dîners prêts en 10 minutes",
    "mediaUrls": ["https://media.kreatoai.com/generation-image-1788….jpg"]
  }'

Crédits

Type	Coût	Ce que vous obtenez
image	2 crédits	Une image au format demandé

Le solde vit sur l'espace, pas sur la clé : GET /v1/workspace et GET /v1/generations le renvoient tous les deux dans credits. Un appel refusé pour solde insuffisant ne débite rien, et une création qui échoue est intégralement remboursée, y compris lorsqu'une mise à jour de nos serveurs l'interrompt.

Champs de la réponse

Champ	Description
`mediaUrl`	URL du fichier produit. null tant que la création n’est pas terminée
`error`	Texte destiné à être montré tel quel à un utilisateur. null tant que rien n’a échoué
`creditsCost`	Ce que cette création a coûté, en crédits
`completedAt`	Fin de la production, en succès comme en échec
`durationSec`, `sourceUrls`	Remplis seulement pour les vidéos produites avant le 26 septembre 2026, qui restent listées

Les fichiers produits vous appartiennent : contrairement aux médias ingérés via /v1/media, ils ne sont soumis à aucune durée de conservation tant que vous ne supprimez pas la création.

Erreurs

Statut	Code	Cause
400	validation zod	Prompt trop court, format inconnu, ou type autre que image
402	`insufficient_credits`	Solde insuffisant. Rien n’a été débité
402	`subscription_required`	L’espace n’a pas d’abonnement en cours
403	`insufficient_scope`	La clé ne porte pas generations:write
404	`generation_not_found`	Identifiant inconnu dans cet espace, ou création supprimée
429	`rate_limit_exceeded`	Trop de requêtes : attendez 60 secondes

Une création peut aussi aboutir en failed après avoir été acceptée : une demande refusée par nos garde-fous de contenu, ou une indisponibilité passagère. Dans les deux cas, error dit quoi faire et les crédits reviennent.