Cours Vibe coding avec Claude Code · Module 10: Clone de TikTok

Couvertures de clips par IA : un modèle vérifié dans la documentation

12 min de lecture
Dans cette leçon11

L'enregistrement est coupé, la légende est prête mais dans le feed le clip accueille le spectateur avec sa première image : un pont sombre et une main floue. L'équipage veut taper quelques mots, par exemple "un coffre plein d'or sur une plage au coucher du soleil", et obtenir une couverture verticale. Une telle image, c'est un modèle qui génère des images à partir d'une description qui la dessine, et Treasure Reels le lui demandera par l'API OpenAI. C'est une fonction de l'application, pas un outil pour écrire du code : le code, c'est toujours Claude Code qui l'écrit, et OpenAI ne fait que peindre les couvertures pour les utilisateurs du clone.

Chaque couverture coûte de l'argent sur ton compte OpenAI, et la règle de la leçon 8_4, tu la connais déjà : la clé reste dans la cale, c'est-à-dire sur le serveur. Le piège est autre : le nom du modèle, qui vieillit plus vite que les connaissances de Claude.

Ce que tu vas apprendre

  • commander une recherche dans la documentation actuelle avant que la moindre ligne de code n'existe ;
  • lire un Route Handler qui appelle l'API d'images avec la clé du serveur et garde le nom du modèle dans une seule constante ;
  • vérifier la limite de la description, une erreur qui ne trahit pas la clé et une couverture de remplacement pour l'équipage sans compte OpenAI ;
  • repérer dans Cursor deux erreurs typiques de l'agent : un modèle sorti de sa mémoire et le paquet OpenAI dans le navigateur.

D'abord, un repérage dans la documentation

Les connaissances de Claude ont une date, et la liste des modèles OpenAI change toutes les quelques semaines. Un modèle que Claude se rappelle bien a pu recevoir une date d'arrêt ou cesser de fonctionner. Tu commences donc par un repérage, comme dans la leçon 5_4 : Claude lit les pages avec les outils intégrés WebSearch et WebFetch, et toi, tu exiges un lien pour chaque constat.

Demande pour Claude Code :

N'écris pas de code. Lis la documentation OpenAI actuelle :
https://developers.openai.com/api/docs/guides/image-generation
https://developers.openai.com/api/docs/deprecations
et le README du paquet openai sur GitHub. Écris : quels modèles
d'images sont actuels, lesquels sont retirés et quand, dans quel
champ l'image revient, si l'on a le droit d'appeler l'API depuis
le navigateur et quelle version de Node.js le paquet exige.
Pour chaque constat, le lien vers la page. À la fin, un plan des
couvertures pour Treasure Reels, sans code.

Tu compares la réponse avec les pages que tu ouvres toi-même, car tu sais depuis la leçon 5_1 que WebFetch donne un extrait, pas la page entière. État en novembre 2026 : la ligne actuelle est gpt-image-2.6 en deux variantes, gpt-image-2.6-sunburst pour le travail détaillé sur l'image et gpt-image-2.6-flare pour la génération rapide, la ligne précédente gpt-image-2.5 fonctionne aussi, le modèle gpt-image-2 est retiré avec un arrêt le 10 février 2027, et gpt-image-1 et les modèles DALL-E ne fonctionnent plus. Trois constats sont plus durables. L'image revient dans le champ b64_json, c'est-à-dire en base64, une image écrite en texte. Le guide avertit qu'avant d'utiliser les modèles GPT Image, une vérification de l'organisation peut être nécessaire dans la console OpenAI. Le README du paquet dit qu'il exige Node.js 22 ou plus récent et qu'il est bloqué par défaut dans le navigateur, pour ne pas exposer la clé.

Le compilateur ne te protégera pas d'un ancien nom. Chez nous, les types du paquet openai actuel énuméraient encore dall-e-3 et gpt-image-1, donc npx tsc --noEmit aurait laissé passer les deux noms, et l'erreur ne serait apparue qu'à la première couverture, sous les yeux de l'équipage.

La demande : la couverture par un Route Handler

Tu transformes le plan du rapport en une demande qui nomme les fichiers, les contraintes et la preuve. Remarque que le nom du modèle n'y figure pas : Claude le prend dans la documentation qu'il vient de lire.

Demande pour Claude Code :

Ajoute la génération de la couverture d'un clip. Installe le paquet
openai. Le Route Handler app/api/cover/route.ts (POST) appelle
images.generate avec le modèle de la documentation lue, écrit dans
une seule constante COVER_MODEL. Clé depuis process.env.OPENAI_API_KEY,
sans NEXT_PUBLIC_ et sans dangerouslyAllowBrowser. Description de 1 à
300 caractères (constante dans lib/cover.ts), image verticale, résultat
de b64_json sous forme d'adresse data:. Erreur de l'API : message
général et code 502, dans le journal seulement le statut et le code.
Sans clé, la route renvoie une couverture de remplacement depuis
public/covers. Le composant CoverGenerator appelle seulement
/api/cover, page /couverture. Ne crée pas le fichier .env.local.
Pour finir, tests de la route, lint, types, build et curl sans clé.

Ce que Claude a écrit : la limite en un seul endroit

Ouvre lib/cover.ts dans Cursor. La limite de la description et la forme de la réponse de la route se trouvent dans un petit fichier que lisent à la fois le serveur et le formulaire :

export const COVER_PROMPT_MAX = 300;

export type CoverResponse =
  | { image: string; placeholder?: boolean }
  | { error: string };

CoverResponse est une union, c'est-à-dire un type "l'un ou l'autre" : la route renvoie soit une image, éventuellement marquée comme de remplacement, soit une erreur. Le champ texte du formulaire reçoit maxLength={COVER_PROMPT_MAX}, mais ce n'est qu'un indice pour le pirate honnête, car la requête peut être envoyée sans passer par le formulaire. La vraie limite, c'est la route qui la vérifie.

Ce que Claude a écrit : les gardiens de la route

Ouvre app/api/cover/route.ts. En haut se trouve le seul nom de modèle du projet, et la fonction POST commence par vérifier la description :

// Le seul endroit avec le nom du modèle. Avant de le changer, vérifie-le dans la documentation OpenAI.
const COVER_MODEL = "gpt-image-2.6-flare";

export async function POST(request: Request) {
  const body: unknown = await request.json().catch(() => null);
  const prompt =
    typeof body === "object" && body !== null && "prompt" in body && typeof body.prompt === "string"
      ? body.prompt.trim()
      : "";
  if (prompt.length === 0 || prompt.length > COVER_PROMPT_MAX) {
    return Response.json(
      { error: `La description de la couverture doit faire de 1 à ${COVER_PROMPT_MAX} caractères` },
      { status: 400 },
    );
  }

.catch(() => null) transforme un contenu qui n'est pas du JSON en null, donc une requête cassée reçoit le code 400 au lieu d'une erreur du serveur. Le type unknown oblige le code à vérifier que prompt est bien une chaîne. Une mauvaise description ne partira pas chez OpenAI, donc tu ne la paieras pas. Le second gardien surveille la clé :

  const apiKey = process.env.OPENAI_API_KEY;
  if (!apiKey) {
    return Response.json({ image: "/covers/placeholder.svg", placeholder: true });
  }

Sans clé, la route renvoie la couverture de remplacement depuis public/covers/ avec le drapeau placeholder, donc l'application fonctionne aussi chez quelqu'un qui n'a pas de compte OpenAI ou qui attend la vérification de l'organisation. La réponse ne trahit ni le nom de la variable ni le fichier de la clé.

Ce que Claude a écrit : l'appel à l'API

C'est seulement maintenant que la route crée le client OpenAI avec la clé et demande une image :

  try {
    const openai = new OpenAI({ apiKey });
    const result = await openai.images.generate({
      model: COVER_MODEL,
      prompt,
      size: "1024x1536",
      quality: "low",
      output_format: "jpeg",
    });
    const b64 = result.data?.[0]?.b64_json;
    if (!b64) {
      return Response.json({ error: "Génération de la couverture momentanément indisponible" }, { status: 502 });
    }
    return Response.json({ image: `data:image/jpeg;base64,${b64}` });

1024x1536 est l'une des trois tailles que recommande le guide OpenAI, et la seule verticale. quality: "low", le guide la recommande pour les brouillons rapides, et du JPEG il dit qu'il est produit plus vite que le PNG. Le base64 de b64_json, la route le colle avec le préfixe data:image/jpeg;base64, pour obtenir une adresse data:, c'est-à-dire une image écrite directement dans l'adresse, que le navigateur affichera sans requête supplémentaire. La couverture ne va pas sur le disque : après un rafraîchissement de la page, elle disparaît, et l'enregistrer est une étape à part.

Ce que Claude a écrit : une erreur sans secrets

Quand OpenAI refuse, le paquet lève une APIError, c'est-à-dire une erreur avec le code HTTP dans le champ status et le code d'erreur dans le champ code :

  } catch (err) {
    if (err instanceof APIError) {
      console.error(`OpenAI a répondu ${err.status ?? "sans statut"} ${err.code ?? ""}`);
      if (err.code === "moderation_blocked") {
        return Response.json(
          { error: "Le filtre de contenu a rejeté cette description. Modifie-la et réessaie." },
          { status: 400 },
        );
      }
    } else {
      console.error("Échec de l'appel à OpenAI");
    }
    return Response.json({ error: "Génération de la couverture momentanément indisponible" }, { status: 502 });
  }
}

Dans le journal n'arrivent que le statut et le code, pas le message d'OpenAI. Ce n'est pas exagéré : chez nous, la réponse à une clé inventée contenait dans le message son début masqué et ses trois derniers caractères. moderation_blocked est, selon le guide, une description rejetée par le filtre de contenu, qu'on ne relance pas sans changer la description, donc l'équipage reçoit le code 400 et la demande d'une autre description. Toute autre erreur donne le code 502, c'est-à-dire "le service derrière moi a échoué", comme pour la météo dans la leçon 8_4.

Ce que Claude a écrit : le composant

components/CoverGenerator.tsx a "use client", un champ de description avec un compteur de caractères et un bouton qui envoie un fetch en POST vers /api/cover. Il n'importe pas le paquet openai et ne connaît pas la clé. L'image est affichée par le composant Image de Next.js :

<Image
  src={result.image}
  alt={`Couverture du clip : ${prompt}`}
  width={1024}
  height={1536}
  unoptimized
  className="h-auto w-full rounded-lg"
/>

Selon la documentation de Next.js, unoptimized sert l'image telle quelle, sans optimisation des images. Une adresse data: est un fichier prêt, et la couverture de remplacement est un SVG, donc il n'y a rien à réduire ici.

La revue du capitaine

  1. La clé et le paquet seulement dans la route. Cherche dans le projet (Cmd+Shift+F sur Mac, Ctrl+Shift+F sous Windows) OPENAI_API_KEY et from "openai" : les deux seulement dans route.ts. NEXT_PUBLIC_ et dangerouslyAllowBrowser n'ont pas une seule occurrence. Puis le test de la leçon 8_4 : chez nous, après le build avec une clé inventée dans .env.local, la recherche d'un fragment de cette clé dans .next/static a donné zéro fichier.
  2. Erreur typique de l'agent : le paquet dans le navigateur. L'agent colle new OpenAI() dans un composant avec "use client". Chez nous, le paquet lancé dans l'environnement de navigateur des tests a refusé de démarrer avec une erreur commençant par It looks like you're running in a browser-like environment.. L'agent aime "corriger" cela par dangerouslyAllowBrowser: true et une clé dans NEXT_PUBLIC_, c'est-à-dire exactement la fuite de la leçon 8_4. Une telle correction, tu l'annules par /rewind.
  3. Seconde erreur typique : le modèle de mémoire. Cherche COVER_MODEL : une seule définition, et sa valeur correspond au rapport du repérage. Un nom de modèle dans un second fichier ou un modèle d'une ligne arrêtée, c'est une correction immédiate.
  4. L'erreur ne fuit pas. Mets une clé inventée dans .env.local, construis et lance l'application, puis envoie un curl à la route. Chez nous, OpenAI a répondu 401 avec le code invalid_api_key, la route a renvoyé {"error":"Génération de la couverture momentanément indisponible"} avec le code 502, et dans le journal du serveur est apparue la ligne OpenAI a répondu 401 invalid_api_key. Une description de 301 caractères a reçu 400, et sans clé la route a renvoyé {"image":"/covers/placeholder.svg","placeholder":true}. Les tests de la route avec un fetch simulé vérifient la même chose sans réseau.
  5. Le coût. La route est ouverte à quiconque connaît l'adresse, et chaque appel va sur ta facture. Avant que Treasure Reels prenne la mer vers les gens, la route reçoit un verrou avec la session de la leçon 8_3 et une limite de couvertures par personne. Les prix actuels, tu les vérifies sur le site d'OpenAI.

Sans compte OpenAI

La couverture de remplacement suffit pour terminer ce module. Si tu as un compte, tu colles la clé toi-même dans .env.local dans Cursor, jamais dans la conversation avec Claude, et les règles deny pour les fichiers .env, tu les reprends de la leçon 8_4 dans ce projet. Souviens-toi aussi de la leçon 9_2 : un worktree est un checkout tout neuf sans .env.local, donc ajoute ce fichier à .worktreeinclude.

Étape suivante

La demande suivante est courte : "Ajoute .env.example avec un OPENAI_API_KEY vide et une exception pour ce fichier dans .gitignore". L'exception est nécessaire, car la ligne .env* de create-next-app cache aussi .env.example. Puis un commit, par exemple "Couvertures de clips par un Route Handler". Enregistrer la couverture comme poster de l'enregistrement est une autre petite demande pour le prochain voyage.

Dans l'éditeur ci-dessous t'attend un générateur de couvertures avec un faux serveur et un panneau réseau. Change l'état de la clé sur le serveur, tape une description trop longue, puis active l'erreur de l'agent avec la clé dans le navigateur et regarde ce qu'on voit dans le panneau réseau.

À retenir : la carte vieillit plus vite que la boussole, donc avant de prendre la mer pour une couverture, vérifie dans le journal de bord que l'île existe encore, et laisse la clé du coffre dans la cale.

Code de cette leçon : App.jsx
// Générateur de couvertures en miniature : faux serveur et faux OpenAI à la place de la vraie API.
// Dans le projet, la route est gérée par app/api/cover/route.ts, et la clé n'est que dans .env.local sur le serveur.
import { useState } from 'react';

const COVER_PROMPT_MAX = 300;
const COVER_MODEL = 'gpt-image-2.6-flare';
const REAL_KEY = 'sk-proj-cale-123';
const KEYS = { none: '', fake: 'sk-proj-inventee-999', real: REAL_KEY };

// Couleur de la couverture calculée à partir de la description : la même description donne la même image.
function paint(prompt) {
  let hash = 0;
  for (const ch of prompt) hash = (hash * 31 + ch.charCodeAt(0)) % 360;
  return { hue: hash, title: prompt.slice(0, 40) };
}

// Faux OpenAI : vérifie la clé et le filtre de contenu, puis peint.
function fakeOpenAI(key, prompt) {
  if (key !== REAL_KEY) return { status: 401, code: 'invalid_api_key' };
  if (/sang|violence/i.test(prompt)) return { status: 400, code: 'moderation_blocked' };
  return { status: 200, cover: paint(prompt) };
}

// Faux Route Handler POST /api/cover : il tourne "sur le serveur", donc il connaît la clé.
function coverRoute(body, serverKey, log) {
  const prompt = typeof body.prompt === 'string' ? body.prompt.trim() : '';
  if (prompt.length === 0 || prompt.length > COVER_PROMPT_MAX) {
    return { status: 400, json: { error: 'La description de la couverture doit faire de 1 à ' + COVER_PROMPT_MAX + ' caractères' } };
  }
  if (!serverKey) return { status: 200, json: { placeholder: true } };
  const res = fakeOpenAI(serverKey, prompt);
  if (res.status === 200) return { status: 200, json: { cover: res.cover } };
  log('OpenAI a répondu ' + res.status + ' ' + res.code);
  if (res.code === 'moderation_blocked') {
    return { status: 400, json: { error: 'Le filtre de contenu a rejeté cette description. Modifie-la et réessaie.' } };
  }
  return { status: 502, json: { error: 'Génération de la couverture momentanément indisponible' } };
}

export default function App() {
  const [prompt, setPrompt] = useState('');
  const [keyMode, setKeyMode] = useState('none');
  const [agentBug, setAgentBug] = useState(false);
  const [result, setResult] = useState(null);
  const [network, setNetwork] = useState([]);
  const [serverLog, setServerLog] = useState([]);

  function handleSubmit(event) {
    event.preventDefault();
    const log = (line) => setServerLog((prev) => [...prev, line]);
    if (agentBug) {
      // Erreur de l'agent : clé dans NEXT_PUBLIC_ et appel à OpenAI directement depuis le navigateur.
      setNetwork((prev) => [...prev, {
        url: 'POST https://api.openai.com/v1/images/generations',
        detail: 'Authorization: Bearer ' + REAL_KEY + ' | model: ' + COVER_MODEL,
        leak: true,
      }]);
      const res = fakeOpenAI(REAL_KEY, prompt);
      setResult(res.status === 200 ? { cover: res.cover } : { error: 'Erreur ' + res.status });
      return;
    }
    const res = coverRoute({ prompt }, KEYS[keyMode], log);
    setNetwork((prev) => [...prev, {
      url: 'POST /api/cover',
      detail: 'contenu : {"prompt": "' + prompt.slice(0, 30) + '"} | réponse ' + res.status,
      leak: false,
    }]);
    setResult(res.json);
  }

  const tooLong = prompt.length > COVER_PROMPT_MAX;

  return (
    <div className="min-h-screen bg-gray-950 p-4 text-white flex flex-col gap-4 md:flex-row">
      <form onSubmit={handleSubmit} className="flex w-full max-w-sm flex-col gap-2">
        <label htmlFor="cover-prompt" className="text-sm font-semibold">Description de la couverture</label>
        <textarea
          id="cover-prompt"
          value={prompt}
          onChange={(e) => setPrompt(e.target.value)}
          rows={3}
          placeholder="Un coffre plein d'or sur une plage au coucher du soleil"
          className="rounded border border-gray-600 bg-gray-900 p-2 text-sm"
        />
        <p className={tooLong ? 'text-xs text-red-400' : 'text-xs text-gray-400'}>
          {prompt.length}/{COVER_PROMPT_MAX} (sans maxLength, pour tester la route)
        </p>
        <button type="submit" className="rounded bg-amber-500 px-4 py-2 font-semibold text-black">
          Générer la couverture
        </button>
        {result && result.error && <p role="alert" className="text-sm text-red-400">{result.error}</p>}
        {result && result.placeholder && (
          <div className="flex aspect-[2/3] w-40 flex-col items-center justify-center rounded-lg bg-sky-900 text-center text-sm">
            <span className="text-4xl">⚓</span>
            <span>couverture de remplacement</span>
          </div>
        )}
        {result && result.cover && (
          <div
            className="flex aspect-[2/3] w-40 items-end rounded-lg p-2 text-sm font-semibold"
            style={{ background: 'linear-gradient(160deg, hsl(' + result.cover.hue + ' 70% 45%), hsl(' + ((result.cover.hue + 60) % 360) + ' 70% 20%))' }}
          >
            {result.cover.title}
          </div>
        )}
      </form>

      <div className="flex-1 space-y-3 text-sm">
        <fieldset className="space-y-1">
          <legend className="font-semibold">Clé dans .env.local sur le serveur</legend>
          {[['none', 'pas de clé'], ['fake', 'clé inventée'], ['real', 'clé valide (simulation)']].map(([value, label]) => (
            <label key={value} className="flex items-center gap-2">
              <input type="radio" name="key" value={value} checked={keyMode === value} onChange={() => setKeyMode(value)} />
              {label}
            </label>
          ))}
        </fieldset>
        <label className="flex items-center gap-2">
          <input type="checkbox" checked={agentBug} onChange={(e) => setAgentBug(e.target.checked)} />
          Erreur de l&apos;agent : SDK dans le navigateur avec une clé de NEXT_PUBLIC_
        </label>
        <div>
          <p className="font-semibold">Panneau réseau du navigateur</p>
          <ul className="space-y-1">
            {network.length === 0 && <li className="text-gray-400">Aucune requête.</li>}
            {network.map((entry, i) => (
              <li key={i} className={entry.leak ? 'rounded bg-red-950 p-2' : 'rounded bg-gray-800 p-2'}>
                <code>{entry.url}</code>
                <br />
                <span className="text-xs">{entry.detail}</span>
              </li>
            ))}
          </ul>
        </div>
        <div>
          <p className="font-semibold">Journal du serveur</p>
          <ul className="text-xs text-gray-300">
            {serverLog.length === 0 && <li>Vide.</li>}
            {serverLog.map((line, i) => <li key={i}>{line}</li>)}
          </ul>
        </div>
      </div>
    </div>
  );
}

Tu as repéré une erreur dans cette leçon ?

Teste tes connaissances

Réponds aux questions de cette leçon. Choisis une réponse pour voir tout de suite si elle est correcte.

  1. 1. À quoi Treasure Reels utilise-t-il l'API d'images d'OpenAI ?

  2. 2. Où Claude a-t-il écrit le nom du modèle d'images, et pourquoi ?

Tâches pratiques dans le jeu

  • Tri horizontal

    Ordonne la ligne par laquelle le Route Handler commence l'appel à l'API d'images :

  1. QuestionL'API d'images dans Treasure Reels
  2. Remets dans l'ordreAppel de génération dans le Route Handler
  3. QuestionLe nom du modèle en un seul endroit

Articles utiles