Documentation

Everything you need to create card news with Kardyy — from the visual editor to the API and MCP integration.

Getting Started

Create your first card news in three steps.

Sign Up

Create a free account with email or Google sign-in.

Open Editor

Choose a layout, add your content, and customize the design.

Export

Download as PNG images, a ZIP bundle, or an MP4 video.

Editor Guide

Slide Management

Add, duplicate, delete, and reorder slides with drag-and-drop
Each slide has its own headline, subtitle, tags, and background image
Undo/redo support across all changes

Text Editing

Headline — Main text, click directly on the preview to edit
Subtitle — Smaller text above or below the headline (supports line breaks)
Tags — Hashtag-style labels displayed at the bottom

Images

Upload from your device or paste a URL
Generate AI images with a text prompt (powered by Gemini)
Edit existing images with AI (describe what to change)

Design Settings

Font family, size, color, and weight
Background color and overlay opacity
Text box styles: none, solid, gradient, or blur
Logo upload and positioning (4 corners)

Layouts

Five layout presets control how content is arranged on each slide.

Layout	ID	Description
Poster	kolektt-default	Full-bleed background image with text overlay. Default layout.
Vinyl	kolektt-pick	Vinyl record design with album art. Great for music content.
Guide	kolektt-guide	Full image with text shadow. Clean, image-focused layout.
Split	kolektt-poi	Top bar with bottom text box. Split layout for structured content.
Find	kolektt-find	Reserved for future use.

Canvas & Export

Canvas Sizes

13 canvas sizes optimized for every major social media platform.

ID	Size (px)	Label	Use Case
1:1	1080 x 1080	Square	Instagram / General
4:5	1080 x 1350	Portrait	Instagram Feed
1200x630	1200 x 630	FB/LinkedIn/X	Facebook, LinkedIn, X Post
1200x675	1200 x 675	X Post	X (Twitter) Post
9:16	1080 x 1920	Story / Reels	Instagram Stories, TikTok
16:9	1280 x 720	YouTube Thumbnail	YouTube Thumbnail
2:3	1000 x 1500	Pinterest Pin	Pinterest

Export Formats

PNG — Individual slide as a high-resolution image
ZIP — All slides bundled into a single download
MP4 — Animated video with slide transitions

API Reference

The Kardyy API lets you generate card images, upload media, and manage API keys programmatically. All endpoints are under /api/v1.

Authentication

All API requests require a Bearer token. API keys use the kd_ prefix.

bash

curl https://www.kardyy.kr/api/v1/cards/generate \
  -H "Authorization: Bearer kd_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Permissions: Each key has scoped permissions.

cards:generate — Generate card images
cards:read — Read card data
images:upload — Upload images

POST /api/v1/cards/generate

Generate card news images from slide data. Returns image URLs or base64-encoded images. Requires cards:generate permission.

Request Body

json

{
  "slides": [
    {
      "headline": "Breaking News",
      "smallTitle": "2026 Update",
      "tags": ["#news", "#update"],
      "imageSrc": "https://example.com/bg.jpg"
    }
  ],
  "layout": "kolektt-default",
  "canvasSize": "4:5",
  "backgroundColor": "#000000",
  "logoSrc": "https://example.com/logo.png",
  "logoPosition": "top-right",
  "returnBase64": false,
  "customDesignSettings": {
    "fontFamily": "Pretendard",
    "fontColor": "#ffffff",
    "headlineFontSize": 48,
    "enableOverlay": true,
    "textBoxStyle": "gradient"
  }
}

Parameters

Field	Type	Required	Description
slides	array	Yes	Array of slide objects (1-10 slides)
slides[].headline	string	No	Main headline text
slides[].smallTitle	string	No	Subtitle (supports \n line breaks)
slides[].tags	string[]	No	Hashtags array
slides[].imageSrc	string	No	Background image URL
layout	string	No	Layout type (see Layouts section)
canvasSize	string	No	"1:1" \| "4:5" \| "9:16" \| "16:9" \| "2:3" \| "1200x630" \| etc. Default: "4:5". See Canvas Sizes.
returnBase64	boolean	No	Return base64 instead of URLs. Default: false

Example

bash

curl -X POST https://www.kardyy.kr/api/v1/cards/generate \
  -H "Authorization: Bearer kd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "slides": [
      { "headline": "Top 5 AI Tools", "smallTitle": "2026 Edition", "tags": ["#AI", "#tools"] },
      { "headline": "1. ChatGPT", "smallTitle": "The pioneer of conversational AI" },
      { "headline": "2. Claude", "smallTitle": "Advanced reasoning and analysis" }
    ],
    "layout": "kolektt-default",
    "canvasSize": "4:5"
  }'

Response

json

{
  "apiVersion": "v1",
  "success": true,
  "data": {
    "count": 3,
    "images": [
      "https://...supabase.co/.../slide-0.png",
      "https://...supabase.co/.../slide-1.png",
      "https://...supabase.co/.../slide-2.png"
    ],
    "template": "classic",
    "canvasSize": "4:5",
    "dimensions": { "width": 1080, "height": 1350 }
  },
  "meta": {
    "processingTimeMs": 2340,
    "rateLimit": { "limit": 100, "remaining": 97 }
  }
}

POST /api/v1/images/upload

Upload an image for use in card generation. Accepts base64 JSON or multipart form-data. Requires images:upload permission. Max 10 MB.

Option 1: JSON with Base64

bash

curl -X POST https://www.kardyy.kr/api/v1/images/upload \
  -H "Authorization: Bearer kd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "data:image/png;base64,iVBORw0KG...",
    "filename": "my-background",
    "folder": "uploads"
  }'

Option 2: Multipart Form-Data

bash

curl -X POST https://www.kardyy.kr/api/v1/images/upload \
  -H "Authorization: Bearer kd_your_api_key" \
  -F "file=@./my-image.png" \
  -F "filename=my-background"

Response

json

{
  "apiVersion": "v1",
  "success": true,
  "data": {
    "url": "https://...supabase.co/.../my-background.png",
    "filename": "uploads/my-background-1706789012-a1b2c3.png",
    "size": 245678,
    "mimeType": "image/png"
  }
}

API Key Management

Manage your API keys programmatically. Authenticate with a Supabase user session token.

GET /api/v1/keys

List all API keys for the authenticated user.

json

{
  "data": {
    "keys": [
      {
        "id": "uuid",
        "key_prefix": "kd_1234567",
        "name": "Production Key",
        "permissions": ["cards:generate", "images:upload"],
        "rate_limit": 100,
        "requests_today": 45,
        "is_active": true
      }
    ]
  }
}

POST /api/v1/keys

Create a new API key. The full key is only returned once.

json

// Request
{
  "name": "Production Key",
  "permissions": ["cards:generate", "images:upload"],
  "rateLimit": 100,
  "expiresInDays": 365
}

// Response
{
  "data": {
    "key": "kd_a1b2c3d4e5f6...",
    "keyPrefix": "kd_a1b2c3d",
    "name": "Production Key"
  },
  "message": "API key created. Save the key now - it will not be shown again."
}

DELETE /api/v1/keys?id=KEY_ID

Revoke an API key by its UUID.

Errors & Rate Limits

Error Response Format

json

{
  "apiVersion": "v1",
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Error Codes

Code	HTTP	Description
UNAUTHORIZED	401	Missing or invalid API key
FORBIDDEN	403	Missing required permission
RATE_LIMITED	429	Daily request limit exceeded
INVALID_REQUEST	400	Missing required fields or invalid parameters
INTERNAL_ERROR	500	Server error

Rate Limits: Default 100 requests/day per API key. Resets at midnight UTC. Current usage is returned in the meta.rateLimit field of every response.

MCP Server

Kardyy exposes an MCP (Model Context Protocol) server for AI assistants like Claude Desktop. This lets AI create and manage card news projects directly.

Claude Desktop Configuration

json

{
  "mcpServers": {
    "kardyy": {
      "command": "npx",
      "args": ["tsx", "./mcp-server/src/index.ts"],
      "env": {
        "CARDNEWS_API_URL": "https://www.kardyy.kr",
        "CARDNEWS_API_KEY": "kd_your_api_key"
      }
    }
  }
}

Available Tools

Content Generation

Tool	Parameters	Description
create_card_images	slides, template, layout, canvasSize, ...	Generate card images from slides data
plan_card_series	topic, slideCount, tone	Generate a content plan from a topic
url_to_card_plan	url, slideCount	Convert a URL/article into a card plan
content_schedule	topic, tone	Generate a weekly content schedule

Media

Tool	Parameters	Description
upload_image	image, filename	Upload a base64 image, returns URL
search_images	query	Search for images via Google
generate_ai_image	prompt, mode, inputImage, aspectRatio	Generate or edit images with AI (Gemini)
proxy_image	url	Proxy an external image to bypass CORS

Project Management

Tool	Parameters	Description
project_list	status, limit	List saved projects/drafts
project_load	draftId	Load a project by ID
project_create	title, canvasSize, layoutType	Create a new project
project_save	draftId, title, status	Update a project
project_delete	draftId	Delete a project

Slide Operations

Tool	Parameters	Description
slide_add	draftId, headline, smallTitle, tags, position	Add a new slide to a project
slide_update	draftId, slideIndex, headline, imageSrc, ...	Update a slide's content or design
slide_remove	draftId, slideIndex	Remove a slide from a project
slide_duplicate	draftId, slideIndex	Duplicate a slide
slide_reorder	draftId, fromIndex, toIndex	Move a slide to a new position

Utility

Tool	Parameters	Description
list_templates	—	Get available card templates

AI Agents

Kardyy includes Gemini-powered AI agents for content planning and image generation.

plan_card_series

Generate a structured card news plan from a topic. The AI creates slide-by-slide content with headlines, descriptions, and image suggestions.

json

{
  "topic": "Top 5 productivity tips for developers",
  "slideCount": 5,
  "tone": "professional"
}

url_to_card_plan

Scrape a URL (article, blog post) and convert it into a card news plan. Extracts key points and structures them as slides.

json

{
  "url": "https://example.com/blog/ai-trends-2026",
  "slideCount": 5
}

generate_ai_image

Generate a new image or edit an existing one using Gemini. Supports custom aspect ratios matching all canvas sizes.

json

{
  "prompt": "Minimalist illustration of a developer workspace",
  "mode": "generate",
  "aspectRatio": "4:5"
}