Kurs vibe coding z Claude Code · Moduł 10: Klon TikToka

Okładki klipów z AI: model sprawdzony w dokumentacji

9 min czytania
W tej lekcji11

Nagranie przycięte, podpis gotowy ale w feedzie klip wita widza pierwszą klatką: ciemny pokład i rozmazana dłoń. Załoga chce wpisać kilka słów, na przykład "skrzynia pełna złota na plaży o zachodzie słońca", i dostać pionową okładkę. Taki obraz narysuje model generujący obrazy z opisu, a Treasure Reels poprosi go o to przez API OpenAI. To funkcja aplikacji, a nie narzędzie do pisania kodu: kod nadal pisze Claude Code, a OpenAI tylko maluje okładki dla użytkowników klonu.

Każda okładka kosztuje na Twoim koncie OpenAI, a zasadę z lekcji 8_4 już znasz: klucz zostaje w ładowni, czyli na serwerze. Nowa jest inna pułapka: nazwa modelu, która starzeje się szybciej niż wiedza Claude.

Czego się nauczysz

  • zlecić research aktualnej dokumentacji, zanim powstanie choć jedna linijka kodu;
  • przeczytać Route Handler, który woła API obrazów z kluczem z serwera i trzyma nazwę modelu w jednej stałej;
  • sprawdzić limit opisu, błąd, który nie zdradza klucza, i okładkę zastępczą dla załogi bez konta OpenAI;
  • wyłapać w Cursorze dwa typowe błędy agenta: model z pamięci i paczkę OpenAI w przeglądarce.

Najpierw zwiad w dokumentacji

Wiedza Claude ma datę, a lista modeli OpenAI zmienia się co kilka tygodni. Model, który Claude dobrze pamięta, mógł już dostać datę wyłączenia albo przestać działać. Dlatego zaczynasz od zwiadu, jak w lekcji 5_4: Claude czyta strony wbudowanymi narzędziami WebSearch i WebFetch, a Ty żądasz linku przy każdym ustaleniu.

Polecenie dla Claude Code:

Nie pisz kodu. Przeczytaj aktualną dokumentację OpenAI:
https://developers.openai.com/api/docs/guides/image-generation
https://developers.openai.com/api/docs/deprecations
oraz README paczki openai na GitHubie. Napisz: które modele obrazów
są aktualne, które są wycofywane i kiedy, w jakim polu wraca obraz,
czy wolno wołać API z przeglądarki i jakiej wersji Node.js wymaga
paczka. Przy każdym ustaleniu link do strony. Na koniec plan okładek
dla Treasure Reels, bez kodu.

Odpowiedź porównujesz ze stronami, które otwierasz sam, bo z lekcji 5_1 wiesz, że WebFetch podaje wyciąg, a nie całą stronę. Stan na listopad 2026: aktualna jest linia gpt-image-2.6 w dwóch odmianach, gpt-image-2.6-sunburst do szczegółowej pracy nad obrazem i gpt-image-2.6-flare do szybkiego generowania, działa też poprzednia linia gpt-image-2.5, model gpt-image-2 jest wycofywany z wyłączeniem 10 lutego 2027, a gpt-image-1 i modele DALL-E już nie działają. Trwalsze są trzy ustalenia. Obraz wraca w polu b64_json, czyli jako base64, obraz zapisany tekstem. Przewodnik ostrzega, że przed użyciem modeli GPT Image może być potrzebna weryfikacja organizacji w konsoli OpenAI. README paczki mówi, że wymaga ona Node.js 22 lub nowszego, a w przeglądarce jest domyślnie zablokowana, żeby nie wystawiać klucza.

Kompilator nie obroni Cię przed starą nazwą. U nas typy aktualnej paczki openai wciąż wymieniały dall-e-3 i gpt-image-1, więc npx tsc --noEmit przepuściłby obie nazwy, a błąd wyszedłby dopiero przy pierwszej okładce, na oczach załogi.

Polecenie: okładka przez Route Handler

Plan z raportu zamieniasz w polecenie, które nazywa pliki, ograniczenia i dowód. Zwróć uwagę, że nazwy modelu w nim nie ma: Claude bierze ją z dokumentacji, którą przed chwilą przeczytał.

Polecenie dla Claude Code:

Dodaj generowanie okładki klipu. Zainstaluj paczkę openai.
Route Handler app/api/cover/route.ts (POST) woła images.generate
z modelem z przeczytanej dokumentacji, zapisanym w jednej stałej
COVER_MODEL. Klucz z process.env.OPENAI_API_KEY, bez NEXT_PUBLIC_
i bez dangerouslyAllowBrowser. Opis od 1 do 300 znaków (stała
w lib/cover.ts), obraz pionowy, wynik z b64_json jako adres data:.
Błąd API: ogólny komunikat i kod 502, w logu tylko status i kod.
Bez klucza trasa oddaje okładkę zastępczą z public/covers.
Komponent CoverGenerator woła tylko /api/cover, strona /okladka.
Pliku .env.local nie twórz. Na koniec testy trasy, lint, typy,
build i curl bez klucza.

Co napisał Claude: limit w jednym miejscu

Otwórz w Cursorze lib/cover.ts. Limit opisu i kształt odpowiedzi trasy leżą w małym pliku, który czytają i serwer, i formularz:

export const COVER_PROMPT_MAX = 300;

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

CoverResponse to unia, czyli typ "jedno albo drugie": trasa oddaje albo obraz, opcjonalnie oznaczony jako zastępczy, albo błąd. Pole tekstowe w formularzu dostaje maxLength={COVER_PROMPT_MAX}, ale to tylko podpowiedź dla uczciwego pirata, bo żądanie da się wysłać z pominięciem formularza. Prawdziwy limit sprawdza trasa.

Co napisał Claude: strażnicy trasy

Otwórz app/api/cover/route.ts. Na górze stoi jedyna nazwa modelu w projekcie, a funkcja POST zaczyna od sprawdzenia opisu:

// Jedyne miejsce z nazwą modelu. Przed zmianą sprawdź ją w dokumentacji 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: `Opis okładki musi mieć od 1 do ${COVER_PROMPT_MAX} znaków` },
      { status: 400 },
    );
  }

.catch(() => null) zamienia treść, która nie jest JSON-em, w null, więc zepsute żądanie dostaje kod 400 zamiast błędu serwera. Typ unknown zmusza kod do sprawdzenia, czy prompt naprawdę jest napisem. Zły opis nie wyjdzie do OpenAI, więc nie zapłacisz za niego. Drugi strażnik pilnuje klucza:

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

Bez klucza trasa oddaje okładkę zastępczą z public/covers/ z flagą placeholder, więc aplikacja działa także u kogoś, kto nie ma konta OpenAI albo czeka na weryfikację organizacji. Odpowiedź nie zdradza nazwy zmiennej ani pliku z kluczem.

Co napisał Claude: wywołanie API

Dopiero teraz trasa tworzy klienta OpenAI z kluczem i prosi o obraz:

  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: "Generowanie okładki chwilowo niedostępne" }, { status: 502 });
    }
    return Response.json({ image: `data:image/jpeg;base64,${b64}` });

1024x1536 to jeden z trzech rozmiarów, które przewodnik OpenAI poleca, i jedyny pionowy. quality: "low" przewodnik zaleca do szybkich szkiców, a o JPEG pisze, że powstaje szybciej niż PNG. Base64 z b64_json trasa skleja z przedrostkiem data:image/jpeg;base64, w adres data:, czyli obraz zapisany wprost w adresie, który przeglądarka pokaże bez kolejnego żądania. Okładka nie trafia na dysk: po odświeżeniu strony zniknie, a zapis to osobny krok.

Co napisał Claude: błąd bez sekretów

Gdy OpenAI odmówi, paczka rzuca APIError, czyli błąd z kodem HTTP w polu status i kodem błędu w polu code:

  } catch (err) {
    if (err instanceof APIError) {
      console.error(`OpenAI odpowiedział ${err.status ?? "bez statusu"} ${err.code ?? ""}`);
      if (err.code === "moderation_blocked") {
        return Response.json(
          { error: "Filtr treści odrzucił ten opis. Zmień go i spróbuj jeszcze raz." },
          { status: 400 },
        );
      }
    } else {
      console.error("Nie udało się wywołać OpenAI");
    }
    return Response.json({ error: "Generowanie okładki chwilowo niedostępne" }, { status: 502 });
  }
}

Do logu trafiają tylko status i kod, a nie komunikat OpenAI. To nie przesada: u nas odpowiedź na zmyślony klucz zawierała w komunikacie jego zamaskowany początek i trzy ostatnie znaki. moderation_blocked to według przewodnika opis odrzucony przez filtr treści, którego nie ponawia się bez zmiany opisu, więc załoga dostaje kod 400 i prośbę o inny opis. Każdy inny błąd to kod 502, czyli "usługa za mną zawiodła", jak przy pogodzie w lekcji 8_4.

Co napisał Claude: komponent

components/CoverGenerator.tsx ma "use client", pole opisu z licznikiem znaków i przycisk, który wysyła fetch metodą POST na /api/cover. Paczki openai nie importuje i klucza nie zna. Obraz pokazuje komponent Image z Next.js:

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

Według dokumentacji Next.js unoptimized podaje obraz tak, jak jest, z pominięciem optymalizacji obrazów. Adres data: to gotowy plik, a zastępcza okładka to SVG, więc nie ma tu czego zmniejszać.

Przegląd kapitana

  1. Klucz i paczka tylko w trasie. Wyszukaj w projekcie (Cmd+Shift+F na Macu, Ctrl+Shift+F na Windowsie) OPENAI_API_KEY i from "openai": oba tylko w route.ts. NEXT_PUBLIC_ i dangerouslyAllowBrowser nie mają ani jednego trafienia. Potem test z lekcji 8_4: u nas po buildzie ze zmyślonym kluczem w .env.local wyszukanie jego fragmentu w .next/static dało zero plików.
  2. Typowy błąd agenta: paczka w przeglądarce. Agent wkleja new OpenAI() do komponentu z "use client". U nas paczka uruchomiona w środowisku przeglądarki z testów odmówiła startu błędem zaczynającym się od It looks like you're running in a browser-like environment.. Agent lubi to "naprawić" przez dangerouslyAllowBrowser: true i klucz z NEXT_PUBLIC_, czyli dokładnie wyciekiem z lekcji 8_4. Taką poprawkę cofasz przez /rewind.
  3. Drugi typowy błąd: model z pamięci. Wyszukaj COVER_MODEL: jedna definicja, a jej wartość zgadza się z raportem ze zwiadu. Nazwa modelu w drugim pliku albo model z wyłączonej linii to poprawka na już.
  4. Błąd nie wycieka. Wpisz do .env.local zmyślony klucz, zbuduj i uruchom aplikację, a potem wyślij curl na trasę. U nas OpenAI odpowiedział 401 z kodem invalid_api_key, trasa oddała {"error":"Generowanie okładki chwilowo niedostępne"} z kodem 502, a w logu serwera stanęła linia OpenAI odpowiedział 401 invalid_api_key. Opis na 301 znaków dostał 400, a bez klucza trasa oddała {"image":"/covers/placeholder.svg","placeholder":true}. Testy trasy z udawanym fetch sprawdzają to samo bez sieci.
  5. Koszt. Trasa jest otwarta dla każdego, kto zna adres, a każde wywołanie idzie na Twój rachunek. Zanim Treasure Reels wypłynie do ludzi, trasa dostaje zamek z sesją z lekcji 8_3 i limit okładek na osobę. Aktualne ceny sprawdzisz na stronie OpenAI.

Bez konta OpenAI

Okładka zastępcza wystarczy, żeby skończyć ten moduł. Jeśli masz konto, klucz wklejasz sam do .env.local w Cursorze, nigdy do rozmowy z Claude, a reguły deny dla plików .env przenosisz z lekcji 8_4 do tego projektu. Pamiętaj też o lekcji 9_2: worktree to świeży checkout bez .env.local, więc dopisz ten plik do .worktreeinclude.

Następny krok

Kolejne polecenie jest krótkie: "Dodaj .env.example z pustym OPENAI_API_KEY i wyjątek dla tego pliku w .gitignore". Wyjątek jest potrzebny, bo linia .env* z create-next-app ukrywa także .env.example. Potem commit, na przykład "Okładki klipów przez Route Handler". Zapis okładki jako poster nagrania to osobne, małe polecenie na następny rejs.

W edytorze poniżej czeka generator okładek z udawanym serwerem i panelem sieci. Zmień stan klucza na serwerze, wpisz za długi opis, a potem włącz błąd agenta z kluczem w przeglądarce i zobacz, co widać w panelu sieci.

Zapamiętaj: mapa starzeje się szybciej niż kompas, więc zanim wypłyniesz po okładkę, sprawdź w dzienniku portowym, czy wyspa jeszcze istnieje, a klucz do skarbca zostaw w ładowni.

Kod do tej lekcji: App.jsx
// Generator okładek w miniaturze: udawany serwer i udawane OpenAI zamiast prawdziwego API.
// W projekcie trasę obsługuje app/api/cover/route.ts, a klucz leży tylko w .env.local na serwerze.
import { useState } from 'react';

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

// Kolor okładki liczony z opisu, żeby ten sam opis dawał ten sam obraz.
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) };
}

// Udawane OpenAI: sprawdza klucz i filtr treści, potem maluje.
function fakeOpenAI(key, prompt) {
  if (key !== REAL_KEY) return { status: 401, code: 'invalid_api_key' };
  if (/krew|przemoc/i.test(prompt)) return { status: 400, code: 'moderation_blocked' };
  return { status: 200, cover: paint(prompt) };
}

// Udawany Route Handler POST /api/cover: działa "na serwerze", więc zna klucz.
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: 'Opis okładki musi mieć od 1 do ' + COVER_PROMPT_MAX + ' znaków' } };
  }
  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 odpowiedział ' + res.status + ' ' + res.code);
  if (res.code === 'moderation_blocked') {
    return { status: 400, json: { error: 'Filtr treści odrzucił ten opis. Zmień go i spróbuj jeszcze raz.' } };
  }
  return { status: 502, json: { error: 'Generowanie okładki chwilowo niedostępne' } };
}

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) {
      // Błąd agenta: klucz z NEXT_PUBLIC_ i wywołanie OpenAI prosto z przeglądarki.
      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: 'Błąd ' + res.status });
      return;
    }
    const res = coverRoute({ prompt }, KEYS[keyMode], log);
    setNetwork((prev) => [...prev, {
      url: 'POST /api/cover',
      detail: 'treść: {"prompt": "' + prompt.slice(0, 30) + '"} | odpowiedź ' + 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">Opis okładki</label>
        <textarea
          id="cover-prompt"
          value={prompt}
          onChange={(e) => setPrompt(e.target.value)}
          rows={3}
          placeholder="Skrzynia pełna złota na plaży o zachodzie słońca"
          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} (bez maxLength, żeby sprawdzić trasę)
        </p>
        <button type="submit" className="rounded bg-amber-500 px-4 py-2 font-semibold text-black">
          Wygeneruj okładkę
        </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>okładka zastępcza</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">Klucz w .env.local na serwerze</legend>
          {[['none', 'brak klucza'], ['fake', 'zmyślony klucz'], ['real', 'poprawny klucz (symulacja)']].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)} />
          Błąd agenta: SDK w przeglądarce z kluczem z NEXT_PUBLIC_
        </label>
        <div>
          <p className="font-semibold">Panel sieci przeglądarki</p>
          <ul className="space-y-1">
            {network.length === 0 && <li className="text-gray-400">Brak żądań.</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">Log serwera</p>
          <ul className="text-xs text-gray-300">
            {serverLog.length === 0 && <li>Pusto.</li>}
            {serverLog.map((line, i) => <li key={i}>{line}</li>)}
          </ul>
        </div>
      </div>
    </div>
  );
}

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Do czego Treasure Reels używa API obrazów OpenAI?

  2. 2. Gdzie Claude zapisał nazwę modelu obrazów i dlaczego?

Zadania praktyczne w grze

  • Układanie w poziomie

    Ułóż linię, którą Route Handler zaczyna wywołanie API obrazów:

  1. PytanieAPI obrazów w Treasure Reels
  2. Ułóż w kolejnościWywołanie generowania w Route Handlerze
  3. PytanieNazwa modelu w jednym miejscu

Przydatne artykuły