트위터 카드 이미지 생성기 에이전트 스킬

트위터 카드 이미지 생성기

X(트위터) 링크 미리보기에 최적화된 이미지를 생성하세요 — 누군가 링크를 공유할 때 타임라인에 나타나는 카드입니다. 트위터 카드는 표준 Open Graph와 다른 고유한 이미지 크기와 렌더링 동작을 가집니다. 이 스킬은 트위터의 2:1 비율과 플랫폼별 특이사항에 맞춘 전체 생성 파이프라인을 다룹니다.

og-image-generator의 6가지 생성 접근 방식과 6가지 비주얼 스타일이 여기에 모두 적용됩니다. 유일한 차이점은 다음과 같습니다: 출력 크기(1200x630 대신 1200x675), X 특화 디자인 적용, 타임라인 안전 영역, 플레이어 카드 지원.

사용 시기

• 사용자가 X/트위터 링크 미리보기, summary_large_image 또는 플레이어 카드 포스터용 1200×675px(2:1) 이미지가 필요한 경우
• 사용자가 twitter:image, 트위터 카드, X 미리보기 이미지, 트윗 미리보기 또는 타임라인 카드 디자인을 언급하는 경우
• 사용자가 다크 모드에 안전한 레이아웃, 상단 60% 콘텐츠 영역 또는 X의 둥근 모서리 잘림에 대비한 20px 가장자리 마스크가 필요한 경우
• 사용자가 이미 og-image-generator를 사용 중이고 동일한 스타일과 파이프라인의 트위터 적응형 변형을 원하는 경우

사용하지 말아야 할 때

• Facebook, LinkedIn, Slack 등에 사용할 일반 OG 이미지(1200×630, 1.91:1) — 대신 og-image-generator를 사용하세요.
• 이미지 파일을 생성하지 않고 HTML 메타 태그만 설정하는 경우 — marketing-skills의 twitter-cards를 사용하세요.
• SVG 출력 — 트위터는 카드 이미지로 SVG를 지원하지 않습니다. PNG 또는 JPG를 사용하세요.
• 노코드 비주얼 편집기 또는 호스팅 API — 에이전트 파이프라인을 실행하는 대신 Oginify를 사용하세요.

호출 시: 처음 사용 시, 이 스킬이 다루는 내용과 중요성을 1~2문장으로 소개한 후 주요 출력을 제공합니다. 이후 사용 또는 사용자가 건너뛰기를 요청하면 바로 주요 출력으로 넘어갑니다.

1. 트위터가 이미지를 소비하는 방식

트위터는 다음 우선순위로 이미지를 읽습니다:

1. twitter:image — 명시적으로 설정된 경우 직접 사용
2. og:image — 트위터 카드 태그가 없으면 OG 이미지로 대체
3. 이미지 없음 — 일반 텍스트 링크 미리보기

핵심 통찰: Facebook과 LinkedIn은 twitter:image를 읽지 않습니다. 트위터만 트위터 카드 태그를 읽습니다. 즉, 실제 렌더링 파이프라인은 공유할 수 있지만 메타데이터에 두 이미지 경로가 모두 필요합니다.

2. 트위터 이미지 사양

카드 유형에 따라 이미지 표시 방식이 결정됩니다:

대부분의 사용 사례에서는 1200x675px의 summary_large_image를 목표로 합니다.

3. 6가지 생성 접근 방식 (트위터 적응형)

og-image-generator §1의 6가지 접근 방식 모두 트위터 이미지에 사용할 수 있습니다. 유일한 차이는 출력 크기입니다. 이 섹션에서는 트위터 특화 적응 사항을 다룹니다. 전체 렌더링 파이프라인 문서는 og-image-generator §1을 참조하세요.

3.1 AI 이미지 생성 (코어 #1)

OG와 동일한 3부분 프롬프트 전략이지만 트위터 특화 프레임을 적용합니다:

Part 1 — Visual description: background, composition, mood
Part 2 — Text specification: EXACT text, in quotes, with size hints
Part 3 — Twitter constraints: "1200x675px, 2:1 aspect ratio, key text in
         upper 60%, dark background preferred for dark mode"

하이브리드 접근 방식(권장): AI가 배경/분위기를 생성하고 Satori가 텍스트를 오버레이합니다. AI 모델이 여전히 어려워하는 중국어 텍스트에 중요하며, 트위터의 ~40% 다크 모드 사용으로 인해 텍스트 정확도가 더욱 두드러집니다.

전체 AI 도구 비교 표(GPT Image 2.0, Flux, Nano Banana, DALL-E 3, Midjourney)는 og-image-generator §1.1을 참조하세요.

3.2 에이전트-네이티브 콘텐츠 인식 워크플로우 (코어 #2)

OG(§1.2)와 동일한 6단계 워크플로우: 콘텐츠 읽기 → 스타일 매칭 → 시각적 요소 추출 → 생성 선택 → 생성 → 검증. 각 단계에서 트위터 특화 추가 사항:

2단계 (스타일 매칭) — 트위터 다크 모드 고려: 다크 배경 스타일(Terminal/CLI, Midnight Ink Magazine, Brutalist 다크 모드) 또는 X용 다크 변형이 있는 스타일을 선호합니다.

3단계 (시각적 요소 추출) — 모바일에서 트위터 타임라인이 ~1:1로 잘리므로 가장 중요한 시각적 요소는 정사각형 안에서 작동해야 합니다. 1200x675에서 작동하는 가로 데이터 리본은 정사각형 잘림에서 보이지 않을 수 있습니다. 1:1에서 잘 보이는 요소를 하나 이상 추출하세요.

4단계 (생성 선택) — 동일한 의사 결정 트리. AI 생성의 경우, "텍스트가 트위터의 ~260px 모바일 렌더링 너비를 견딜 수 있는가?"를 추가하세요.

6단계 (검증) — OG 검사와 트위터 특화 검사(§8)를 모두 실행합니다.

3.3 Satori + resvg (코드 기반)

OG와 동일한 파이프라인입니다. 높이를 630에서 675로 변경하세요. 전체 구현은 og-image-generator §1.3을 참조하세요.

// Shared endpoint serves both OG and Twitter:
export async function GET(req: Request) {
  const { searchParams } = new URL(req.url);
  const title = searchParams.get('title') ?? 'Default';
  const platform = searchParams.get('platform') ?? 'og'; // 'og' | 'twitter'

  const width = 1200;
  const height = platform === 'twitter' ? 675 : 630;

  return new ImageResponse(
    <OgTemplate title={title} height={height} />,
    { width, height },
  );
}

그런 다음 페이지 메타데이터에서:

const ogUrl = `/og?title=${encodeURIComponent(title)}`;
const twitterUrl = `/og?title=${encodeURIComponent(title)}&platform=twitter`;

export const metadata: Metadata = {
  openGraph: {
    images: [{ url: ogUrl, width: 1200, height: 630 }],
  },
  twitter: {
    card: 'summary_large_image',
    images: [twitterUrl],  // Twitter-specific 1200x675
  },
};

3.4 Puppeteer, 관리 서비스, JSON 설정

OG와 동일 — 뷰포트/높이를 630 대신 675로 설정하세요. og-image-generator §1.4–1.6을 참조하세요. v3 페이지 우선순위 시스템(S/A/B/C) 및 파이프라인 선택에 대해서는 content-strategy.md 및 pipeline-guide.md를 참조하세요.

4. X 특화 디자인 고려 사항

트위터는 Facebook/LinkedIn과 다르게 이미지를 렌더링합니다. 다음 사항을 염두에 두고 디자인하세요:

다크 모드(사용자의 약 40%): 이미지는 피드에서 트윗에 둘러싸여 인라인으로 표시됩니다. 어두운 배경은 자연스럽게 어우러지고, 밝은 배경은 눈에 띄지만 다크 모드에서 거슬릴 수 있습니다. 모든 템플릿에는 다크 변형 또는 다크 모드 친화적 기본값이 있어야 합니다. 6가지 스타일 중 Terminal/CLI, Midnight Ink Magazine, Brutalist(검은 배경)는 원래 다크 모드 친화적입니다. Swiss Minimal과 Newspaper는 다크 모드 대안을 제공해야 합니다.

타임라인 잘림(모바일): 모바일에서 summary_large_image 이미지는 트윗이 확장될 때까지 타임라인에서 ~1:1로 잘립니다. 전체 2:1 이미지는 탭했을 때만 표시됩니다. 가장 중요한 콘텐츠(제목, 주요 비주얼)는 이미지의 상단 60%에 배치하세요. 잘림을 견디는 중앙 정사각형 영역입니다. 절대 하단 20%에 중요한 텍스트를 배치하지 마세요.

작은 크기에서 텍스트 가독성: 타임라인 이미지는 모바일 피드에서 ~260px 너비로 표시됩니다. 텍스트가 읽을 수 있도록 1/4 스케일(~300px 너비)으로 템플릿을 테스트하세요. 이는 OG의 ~500px 데스크톱 피드 크기보다 더 엄격합니다.

가장자리 마스크: 트위터는 카드 이미지에 미세한 둥근 모서리 마스크를 적용합니다. 로고나 중요한 요소를 가장자리 20px 이내에 배치하면 부분적으로 잘릴 위험이 있습니다.

트위터 권장 템플릿 적응(스타일별):

5. 플레이어 카드 포스터

비디오/오디오 콘텐츠의 경우 player 카드 유형에는 포스터 이미지가 필요합니다:

<meta name="twitter:card" content="player">
<meta name="twitter:player" content="https://example.com/player.html">
<meta name="twitter:player:width" content="480">
<meta name="twitter:player:height" content="480">
<meta name="twitter:image" content="https://example.com/poster.jpg">

포스터 이미지는 사용자가 재생을 탭하기 전에 표시됩니다. 매력적인 썸네일로 디자인하세요. 재생 버튼 오버레이(원 안에 중앙 삼각형), 비디오 제목, 콘텐츠의 프레임을 포함하세요. 동일한 2:1 비율 권장 사항이 적용됩니다. 재생 버튼은 중앙 정사각형 영역에서 가장 큰 요소여야 합니다.

AI 생성 포스터의 경우: "중앙 재생 버튼이 있는 비디오 썸네일, 상단 1/3에 제목 텍스트, 검은 배경, 1200x675px"로 프롬프트하세요.

6. 스타일 시스템 (OG와 공유 — 16가지 스타일)

트위터 이미지는 og-image-generator §3 및 references/style-system-v3.md의 동일한 16가지 비주얼 스타일을 사용합니다. 모든 템플릿이 트위터에서 작동합니다. 캔버스 높이를 675px로 변경하기만 하면 됩니다.

X 최고 성능: 터미널, 브루탈리스트, 네오-브루탈리즘, 다크 그라데이션, 베이퍼웨이브 — 높은 대비 + 다크 배경이 X 타임라인에 최적. X 피해야 할 것: 다크 변형이 없는 지나치게 기업적인 온-브랜드 스타일; 다크 모드 타임라인에서 순백색 배경.

7. 폰트 & 타이포그래피

OG와 동일한 규칙입니다. og-image-generator references/typography.md를 참조하세요.

트위터 특화 추가 사항: 타임라인 이미지가 ~260px 너비로 렌더링되므로(OG의 ~500px 데스크톱 피드 대비), 최소 글꼴 크기를 4px 늘립니다. 24px 대신 28px 최소값을 사용하세요.

8. 에이전트 YAML 검사

checks:
  # P0 — must pass
  - id: dimensions-twitter
    description: twitter:image is 1200x675px (2:1) or 1200x628px (cross-platform)
  - id: card-type-match
    description: twitter:card is summary_large_image when using a large image
  - id: absolute-url
    description: twitter:image URL is absolute (https://) and publicly accessible
  - id: format
    description: Image format is PNG, JPG, or WebP (not SVG)

  # P1 — should pass
  - id: og-fallback
    description: og:image is also set (as fallback for platforms that don't read twitter:image)
  - id: timeline-safe-zone
    description: Critical text and primary visual anchor are in the top 60%; nothing critical in bottom 20%
  - id: square-crop-survival
    description: The most important visual element reads correctly in a 1:1 center crop (mobile timeline)
  - id: dark-mode
    description: Template includes a dark-background variant or uses a dark-friendly default style
  - id: edge-mask-clearance
    description: Logos and critical elements are ≥20px from all edges (Twitter rounded corner mask)

  # P2 — nice to have
  - id: cross-platform-compatible
    description: Same image at 1200x628px works for both OG and Twitter without separate generation
  - id: ai-text-validated
    description: If AI-generated, all text was validated against source — no hallucinated or misspelled text
  - id: player-poster
    description: Player card pages have a dedicated poster image with play button
  - id: content-aware-twitter
    description: Image reflects page-specific content, not just a title in a Twitter-sized template

9. 흔한 실수

1. 잘못된 비율: 조정 없이 OG의 1200x630(1.91:1)을 사용하는 경우. 트위터가 이를 허용하지만, 1200x675(2:1)가 카드를 더 잘 채우고 레터박싱을 방지합니다.
2. 누락된 twitter:image 태그: OG 대체에만 의존하는 경우 — 명시적인 twitter:image 없이는 트위터가 어떤 이미지를 선택할지 제어할 수 없습니다.
3. 하단 20%의 텍스트: 트위터는 모바일에서 이미지를 ~1:1로 자릅니다. 하단 근처의 중요한 텍스트가 타임라인에서 잘립니다.
4. 다크 모드 고려 없음: 밝은 배경 이미지는 트위터의 다크 모드 타임라인에서 거슬립니다. 사용자의 약 40%가 다크 모드를 사용합니다.
5. SVG 사용: 트위터는 카드 이미지로 SVG를 지원하지 않습니다. 항상 PNG 또는 JPG를 출력하세요.
6. 정적 첫 프레임이 없는 GIF: 트위터는 GIF의 첫 번째 프레임만 표시합니다. 프레임 1이 의미 있는 정지 이미지인지 확인하세요.
7. 260px 뷰에서 AI 텍스트 환각: 전체 크기에서 올바르게 보이는 AI 생성 텍스트가 작게 렌더링될 때 깨진 문자가 나타날 수 있습니다. 1/4 스케일로 검증하세요.
8. 가장자리에 닿는 로고: 트위터의 둥근 모서리 마스크가 가장자리에서 ~10px을 자릅니다. 로고를 가장자리에서 ≥20px 떨어뜨리세요.

10. 테스트

• 카드 유효성 검사기: https://cards-dev.twitter.com/validator — 카드가 어떻게 렌더링될지 정확히 보여줍니다. 미리 보려면 URL을 붙여넣으세요.
• 수동 테스트: 테스트 계정에서 링크를 트윗한 다음 타임라인 및 확장 뷰를 확인하세요.
• 다크 모드 테스트: 라이트 모드와 다크 모드 트위터 클라이언트에서 카드를 확인하세요.
• 캐시 무효화: 트위터는 카드 데이터를 적극적으로 캐시합니다(최대 7일). 변경 후 카드 유효성 검사기를 사용하여 강제로 다시 스크랩하세요.
• 모바일 잘림 테스트: 1:1 비율로 카드를 스크린샷(675x675 중앙으로 잘라)하여 정사각형 잘림이 페이지 콘텐츠를 여전히 전달하는지 확인하세요.

11. 관련 스킬

이러한 스킬은 선택 사항입니다. 이 스킬은 독립적으로 작동합니다. 추가 기능이 필요하면 설치하세요:

동일 레포지토리 (항상 함께 설치):

• og-image-generator: OG 이미지 생성(1200x630, 1.91:1) — 전체 렌더링 파이프라인, 6가지 모든 스타일, 시드 템플릿, 타이포그래피 가이드, Satori 제약 사항. 이 트위터 카드 생성기는 전체 인프라를 재사용합니다.

별도 레포지토리 (설치 여부 선택 가능):

• twitter-cards (marketing-skills): twitter:card, twitter:site, twitter:creator에 대한 HTML 메타 태그 설정, 유효성 검사. 태그를 SET하는 방법을 처리합니다. 이 스킬은 이미지를 CREATE하는 방법을 처리합니다.
• open-graph (marketing-skills): og:title, og:image, og:url에 대한 HTML 메타 태그 설정, 플랫폼 테스트 도구
• social-share-generator (marketing-skills): 사용자가 X에 링크를 공유할 때 트위터 카드 데이터를 소비하는 공유 버튼 UI