카드티온 API v1

card.tion.kr 은 카드뉴스 이미지를 만드는 플랫폼입니다. 사람은 웹 스튜디오에서, AI 에이전트는 이 REST API로 문구 생성 → 디자인 → PNG 출력 전 과정을 제어합니다.

AI 에이전트라면: GET /api/v1/schema 하나로 전체 계약(덱 스키마·프리셋·배경·엔드포인트)을 기계가 읽을 수 있는 JSON으로 받을 수 있습니다. 그 문서만으로 자율 동작이 가능하도록 설계되었습니다.

인증

서버-투-서버 호출은 X-API-KEY 헤더를 사용합니다(발급: 관리자). 키 없이도 호출은 가능하지만 렌더는 IP당 일일 제한이 있습니다.

가장 빠른 시작 — 원샷 생성

curl -s https://card.tion.kr/api/v1/generate \
  -H 'X-API-KEY: ct_...' -H 'Content-Type: application/json' \
  -d '{
    "topic": "아침 루틴으로 삶이 바뀌는 5가지 이유",
    "reference": "(선택) 반영할 기사/보고서 원문",
    "slides": "auto",
    "ratio": "1:1"
  }'

응답: 생성된 덱 JSON + 저장된 deck_id + 슬라이드별 PNG URL + ZIP.

단계별 제어

엔드포인트설명
GET /api/v1/schema머신리더블 전체 계약 (덱 스키마, 프리셋, 문법)
GET /api/v1/presets스타일 프리셋·액센트·비율 목록
GET /api/v1/backgrounds?cat=다크배경 라이브러리 (내장 그라디언트/단색 + PDS 포토)
POST /api/v1/copy주제 → 덱 JSON (AI 문구). rewrite_slide:N 로 한 장만 다시 쓰기
POST /api/v1/decks · GET/PUT /api/v1/decks/{id}덱 저장/조회/수정 (수정은 edit_token 또는 API 키)
POST /api/v1/preview덱+슬라이드 번호 → 렌더와 동일한 HTML (경량 미리보기)
POST /api/v1/render덱 → 1080px PNG. async:true 면 job id 반환 후 GET /api/v1/render/{job} 폴링
POST /api/v1/upload배경 이미지 업로드 (multipart file)

덱(deck) JSON — 단일 계약

{
  "title": "아침 루틴 5가지",
  "topic": "아침 루틴으로 삶이 바뀌는 이유",
  "brand": "ROBOTION",
  "ratio": "1:1",                    // 1:1 | 4:5 | 9:16
  "style": {
    "preset": "photo-dark",          // photo-dark | white-card | badge-title | bold-white | noir-gold
    "accent": "#FFC845",
    "overlay": 0.45                  // 사진 위 어두운 스크림 0~0.85
  },
  "slides": [
    {
      "role": "cover",               // cover | content | closing
      "badge": "INSIGHT",
      "headline": "지금부터 [실천]하세요",   // [대괄호] = 액센트 강조
      "body": "오늘부터 하나씩 적용해 보세요.",
      "align": "center",             // center | left | bottom
      "show_pagenum": true,
      "bg": {"type":"builtin","id":"grad-ember"}
      //     {"type":"gradient","value":"linear-gradient(...)"}
      //     {"type":"color","value":"#0a2540"}
      //     {"type":"url","url":"https://.../photo.jpg"}
    }
  ]
}

렌더 응답 예시

{
  "ok": true,
  "images": [
    {"no":1, "url":"https://card.tion.kr/renders/aB3xK9/qW.../slide-01.png", "w":1080, "h":1080}
  ],
  "zip": "https://card.tion.kr/renders/aB3xK9/qW.../deck.zip",
  "ms": 9214
}

렌더 결과물은 7일간 보관됩니다. 영구 보관이 필요하면 즉시 다운로드하세요.

제한

ROBOTION API · card.tion.kr