Créer une image : génération d'images par API

Générez une image à partir d’un template image, en un seul appel synchrone. Vous envoyez du JSON, vous récupérez un PNG, un JPEG ou un WebP : sous forme d’URL signée ou directement en octets.

POST https://api.templatefox.com/v1/image/create

Authentification : clé API dans l’en-tête x-api-key. Crédits : 1 crédit par génération réussie (remboursé automatiquement si le rendu échoue).

La génération d’images fonctionne avec les templates image : un canevas unique de taille fixe (par exemple 1080×1080), conçu dans l’éditeur. Un template PDF renvoie une erreur 400 ; pour les documents, utilisez create-pdf.

Requête

Champs essentiels

Seul template_id est obligatoire. Les éléments à changer passent par modifications, chacun désigné par le nom de calque que vous lui avez donné dans le panneau Layers de l’éditeur :

Champ	Type	Description
template_id	string	L’identifiant de 12 caractères de votre template image (à copier depuis la liste des images du tableau de bord).
modifications	array	Les éléments à changer, chacun désigné par le name de son calque. Voir Modifications.

curl TypeScript Python Go PHP Ruby Java C#

Copier

curl -X POST https://api.templatefox.com/v1/image/create \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "template_id": "HMQywVpZxqAM",
  "modifications": [
    { "name": "title", "text": "Summer Sale -50%" },
    { "name": "product_image", "image_url": "https://example.com/photo.jpg" }
  ]
}'

const response = await fetch("https://api.templatefox.com/v1/image/create", {
method: "POST",
headers: {
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  template_id: "HMQywVpZxqAM",
  modifications: [
    { name: "title", text: "Summer Sale -50%" },
    { name: "product_image", image_url: "https://example.com/photo.jpg" },
  ],
}),
});

const { url } = await response.json();

import requests

response = requests.post(
  "https://api.templatefox.com/v1/image/create",
  headers={"x-api-key": "YOUR_API_KEY"},
  json={
      "template_id": "HMQywVpZxqAM",
      "modifications": [
          {"name": "title", "text": "Summer Sale -50%"},
          {"name": "product_image", "image_url": "https://example.com/photo.jpg"},
      ],
  },
)

print(response.json()["url"])

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
)

func main() {
  payload, _ := json.Marshal(map[string]any{
      "template_id": "HMQywVpZxqAM",
      "modifications": []map[string]any{
          {"name": "title", "text": "Summer Sale -50%"},
          {"name": "product_image", "image_url": "https://example.com/photo.jpg"},
      },
  })

  req, _ := http.NewRequest("POST", "https://api.templatefox.com/v1/image/create", bytes.NewReader(payload))
  req.Header.Set("x-api-key", "YOUR_API_KEY")
  req.Header.Set("Content-Type", "application/json")

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()

  body, _ := io.ReadAll(resp.Body)
  fmt.Println(string(body))
}

<?php
$ch = curl_init('https://api.templatefox.com/v1/image/create');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
      'x-api-key: YOUR_API_KEY',
      'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
      'template_id' => 'HMQywVpZxqAM',
      'modifications' => [
          ['name' => 'title', 'text' => 'Summer Sale -50%'],
          ['name' => 'product_image', 'image_url' => 'https://example.com/photo.jpg'],
      ],
  ]),
]);

$response = json_decode(curl_exec($ch), true);
echo $response['url'];

require 'net/http'
require 'json'

uri = URI('https://api.templatefox.com/v1/image/create')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri, {
'x-api-key'    => 'YOUR_API_KEY',
'Content-Type' => 'application/json'
})
request.body = {
template_id: 'HMQywVpZxqAM',
modifications: [
  { name: 'title', text: 'Summer Sale -50%' },
  { name: 'product_image', image_url: 'https://example.com/photo.jpg' }
]
}.to_json

response = JSON.parse(http.request(request).body)
puts response['url']

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var client = HttpClient.newHttpClient();

var body = """
{
"template_id": "HMQywVpZxqAM",
"modifications": [
  { "name": "title", "text": "Summer Sale -50%" },
  { "name": "product_image", "image_url": "https://example.com/photo.jpg" }
]
}
""";

var request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.templatefox.com/v1/image/create"))
  .header("x-api-key", "YOUR_API_KEY")
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(body))
  .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using System.Net.Http;
using System.Net.Http.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

var response = await client.PostAsJsonAsync(
  "https://api.templatefox.com/v1/image/create",
  new {
      template_id = "HMQywVpZxqAM",
      modifications = new object[] {
          new { name = "title", text = "Summer Sale -50%" },
          new { name = "product_image", image_url = "https://example.com/photo.jpg" }
      }
  }
);

Console.WriteLine(await response.Content.ReadAsStringAsync());

Ou passez par l’un de nos SDK officiels : TypeScript, Python, Go, PHP, Ruby, Java, C#.

Tous les paramètres

Champ	Type	Obligatoire	Défaut	Description
template_id	string	✅	—	Identifiant court du template, 12 caractères.
modifications	array	—	—	Les éléments à changer, désignés par le name de leur calque. Voir Modifications. 100 éléments maximum.
format	string	—	"png"	Format de sortie : "png" (sans perte, transparence possible), "jpeg" (plus léger, sans transparence) ou "webp" (compression moderne).
width	integer	—	largeur du template	Largeur de sortie, en pixels ; la hauteur suit le format du template. Minimum 100, maximum 4000. Par défaut, la largeur native du canevas du template.
quality	integer	—	85	Qualité de compression pour jpeg et webp (1 à 100). Ignorée pour png.
export_type	string	—	"url"	"url" dépose l’image sur notre CDN et renvoie une URL signée. "binary" renvoie directement les octets de l’image.
expiration	integer	—	86400	Durée de validité de l’URL, en secondes. Minimum 60, maximum 604800 (7 jours). S’applique uniquement avec export_type="url".
filename	string	—	"document"	Nom de fichier personnalisé (sans extension). Lettres, chiffres, _, - et . uniquement. 100 caractères maximum.
store_s3	boolean	—	false	Envoie le fichier dans votre bucket S3 configuré plutôt que sur notre CDN. Nécessite une intégration S3.
s3_filepath	string	—	—	Préfixe de chemin dans votre bucket S3. Remplace default_prefix. 500 caractères maximum.
s3_bucket	string	—	—	Remplace le nom de bucket de votre intégration S3 (3 à 63 caractères, en minuscules).
version	string	—	—	Tag de version du template (par exemple "prod") ou numéro de version (par exemple "3"). Sans version, le brouillon en cours est utilisé. 50 caractères maximum.

Taille

Le template fixe le format du canevas (par exemple un carré Instagram en 1080×1080, ou une carte Open Graph en 1200×630). width règle la résolution de sortie en pixels ; la hauteur est déduite du template, l’image n’est donc jamais déformée. Sans width, le rendu se fait à la taille native du template ; une valeur plus grande (par exemple 2160) donne un export en plus haute résolution.

Modifications

Chaque élément de modifications cible un calque par le name que vous avez défini dans le panneau Layers de l’éditeur, puis change une ou plusieurs de ses propriétés :

Propriété	Type	Description
name	string	Nom du calque à modifier (obligatoire).
text	string	Remplace le texte du calque. Le texte est rendu tel quel : ni le HTML ni les {{ }} ne sont interprétés.
image_url	string	Définit l’image du calque : la source pour un calque image, une background-image pour tout autre calque. Doit être une URL http(s).
color	string	Couleur du texte (toute couleur CSS).
background	string	Couleur de fond (toute couleur CSS).
hidden	boolean	Masque (true) ou affiche (false) le calque.

Bon à savoir :

• Nommage. name correspond au nom du calque dans le panneau Layers (à défaut, à l’identifiant de l’élément). Renommez un calque dans le panneau Layers pour lui donner un name stable. Le calque réservé background, le fond de l’image, existe dans tous les templates image.
• Les noms inconnus sont ignorés. Si un name ne correspond à aucun calque, le rendu réussit quand même et la réponse le signale dans warnings.
• Un nom partagé s’applique partout. Si plusieurs calques portent le même nom, la modification s’applique à chacun d’eux.

Réponse

export_type = "url" (par défaut)

Renvoie un objet JSON avec une URL signée vers l’image générée.

{
  "url": "https://cdn.templatefox.com/generated/abc123/social-card.png",
  "filename": "social-card.png",
  "credits_remaining": 99,
  "expires_in": 86400
}

Champ	Type	Description
url	string	URL signée pour télécharger l’image (expire au bout de expires_in secondes).
filename	string	Nom de fichier final de l’image générée.
credits_remaining	number	Crédits restants sur le solde de votre équipe après cet appel.
expires_in	number	Nombre de secondes avant l’expiration de l’URL signée.
warnings	array	Présent uniquement quand le name d’une modification ne correspond à aucun élément : un message par nom ignoré.

export_type = "binary"

Renvoie l’image brute, en image/png, image/jpeg ou image/webp (selon format). Pratique pour transmettre le fichier directement à un utilisateur ou le stocker vous-même. expiration, filename et les options S3 sont ignorés.

En-têtes de la réponse :

Content-Type: image/png
Content-Disposition: attachment; filename="HMQywVpZxqAM.png"
X-Credits-Remaining: 99

store_s3 = true

Quand l’envoi vers S3 est demandé, la réponse indique où le fichier a été déposé dans votre bucket, au lieu de renvoyer une URL :

{
  "s3_bucket": "my-image-bucket",
  "s3_key": "social/2026/01/social-card.png",
  "filename": "social-card.png",
  "credits_remaining": 99
}

Formats et taille

Choisissez format et width selon l’endroit où l’image sera utilisée :

curl TypeScript Python Go

Copier

curl -X POST https://api.templatefox.com/v1/image/create \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "template_id": "HMQywVpZxqAM",
  "modifications": [{ "name": "title", "text": "Welcome aboard" }],
  "format": "webp",
  "width": 1200,
  "quality": 90
}'

const response = await fetch("https://api.templatefox.com/v1/image/create", {
method: "POST",
headers: {
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  template_id: "HMQywVpZxqAM",
  modifications: [{ name: "title", text: "Welcome aboard" }],
  format: "webp",
  width: 1200,
  quality: 90,
}),
});

const { url } = await response.json();

import requests

response = requests.post(
  "https://api.templatefox.com/v1/image/create",
  headers={"x-api-key": "YOUR_API_KEY"},
  json={
      "template_id": "HMQywVpZxqAM",
      "modifications": [{"name": "title", "text": "Welcome aboard"}],
      "format": "webp",
      "width": 1200,
      "quality": 90,
  },
)

print(response.json()["url"])

payload, _ := json.Marshal(map[string]any{
  "template_id": "HMQywVpZxqAM",
  "modifications": []map[string]any{{"name": "title", "text": "Welcome aboard"}},
  "format":      "webp",
  "width":       1200,
  "quality":     90,
})

req, _ := http.NewRequest("POST", "https://api.templatefox.com/v1/image/create", bytes.NewReader(payload))
req.Header.Set("x-api-key", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Réponse binaire

Avec export_type à "binary", vous recevez directement les octets de l’image : pratique pour les transmettre à l’utilisateur ou les enregistrer sur disque, sans passer par le CDN.

curl TypeScript Python Go

Copier

curl -X POST https://api.templatefox.com/v1/image/create \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
--output social-card.png \
-d '{
  "template_id": "HMQywVpZxqAM",
  "modifications": [{ "name": "title", "text": "Welcome aboard" }],
  "export_type": "binary"
}'

import fs from "node:fs";

const response = await fetch("https://api.templatefox.com/v1/image/create", {
method: "POST",
headers: {
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  template_id: "HMQywVpZxqAM",
  modifications: [{ name: "title", text: "Welcome aboard" }],
  export_type: "binary",
}),
});

const buffer = Buffer.from(await response.arrayBuffer());
fs.writeFileSync("social-card.png", buffer);

import requests

response = requests.post(
  "https://api.templatefox.com/v1/image/create",
  headers={"x-api-key": "YOUR_API_KEY"},
  json={
      "template_id": "HMQywVpZxqAM",
      "modifications": [{"name": "title", "text": "Welcome aboard"}],
      "export_type": "binary",
  },
)

with open("social-card.png", "wb") as f:
  f.write(response.content)

payload, _ := json.Marshal(map[string]any{
  "template_id": "HMQywVpZxqAM",
  "modifications": []map[string]any{{"name": "title", "text": "Welcome aboard"}},
  "export_type": "binary",
})

req, _ := http.NewRequest("POST", "https://api.templatefox.com/v1/image/create", bytes.NewReader(payload))
req.Header.Set("x-api-key", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

out, _ := os.Create("social-card.png")
defer out.Close()
io.Copy(out, resp.Body)

Erreurs

Statut	Quand
400	Le template n’est pas un template image (utilisez create-pdf), ou il compte plus d’une page.
401	Clé API absente ou invalide.
402	Le solde de crédits de votre équipe est à 0.
403	Le template n’existe pas ou n’appartient pas à votre équipe.
404	La version demandée n’existe pas.
422	Un paramètre est manquant ou invalide.
429	Limite de requêtes atteinte (voir les en-têtes de la réponse).
500	Erreur serveur. Si le rendu lui-même échoue, le crédit est remboursé automatiquement.

La liste complète est dans la vue d’ensemble de la référence API.