CLI & API Guide | ModKie Docs

Call registered capabilities through the site API — no direct provider keys required. Image generation, video generation, and stock material search are supported via API Key.

Recommended reading order

This page (configuration and API fields)
Image generation (commands, presets, examples)
Video generation (scenes, models, async polling)
Material search (Pexels/Pixabay stock footage)
Live schema: GET https://modkie.com/api/actions/{capabilityId}/schema

All external automation uses Authorization: Bearer sk-xxx against /api/actions/*.

Quick start (HTTP)

Create an API key at Settings → API Keys (sk-...)
Generate an image:

curl -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -X POST https://modkie.com/api/actions/ai.image.generate_and_wait \
  -d '{"preset":"logo","prompt":"minimal tech logo"}'

Discover capabilities: GET https://modkie.com/api/actions

CLI setup

The CLI ships inside the project repo (not a separate npm package). Clone the repo, then:

pnpm ads login --host https://modkie.com --api-key sk-xxxxxxxx
pnpm ads image generate --preset logo --prompt "minimal tech logo" --out ./logo.png --json

Or use environment variables:

ADS_HOST=https://modkie.com
ADS_API_KEY=sk-xxxxxxxx

Config priority: ADS_HOST + ADS_API_KEY env vars override ~/.adsgency/config.json.

Authentication

Authorization: Bearer sk-xxxxxxxx

Or:

X-Api-Key: sk-xxxxxxxx

CLI commands

Command	Description
`ads login --host <url> --api-key <sk-xxx>`	Save config to `~/.adsgency/config.json`
`ads config get`	Show host (apiKey masked)
`ads actions list`	List capabilities
`ads actions schema <id>`	Show input schema
`ads image generate ...`	Generate image and wait
`ads image query --task-id <uuid>`	Poll an image task
`ads video generate ...`	Generate video and wait
`ads video query --task-id <uuid>`	Poll a video task
`ads material queries --script "..."`	LLM search terms from script
`ads material search --queries "a,b"`	Search Pexels/Pixabay
`ads material import --file materials.json`	Import selected clips
`ads material auto --script "..."`	Script → search → import

See topic pages: Image · Video · Materials.

Image input fields

Shared by ai.image.generate and ai.image.generate_and_wait (timeoutMs only on generate_and_wait):

Field	Type	Required	CLI flag	Notes
`prompt`	string	yes	`--prompt`	Image description
`preset`	enum	no	`--preset`	`logo`, `web-hero`, `web-section`, `og-image`
`scene`	enum	no	`--scene`	`text-to-image`, `image-to-image`
`provider`	string	no	`--provider`	Default `kie`
`model`	string	no	`--model`	Override default model
`aspectRatio`	string	no	`--aspect`	e.g. `16:9`, `1:1`
`resolution`	enum	no	`--resolution`	`2k`, `4k`
`timeoutMs`	number	no	`--timeout`	Default 180000
`imageInput`	string[]	no	—	Reference URLs (API only)
`options`	object	no	—	Provider passthrough (API only)
`workspaceId`	string	no	—	Creative workspace (API only)

Video input fields

Shared by ai.video.generate and ai.video.generate_and_wait:

Field	Type	Required	CLI flag	Notes
`prompt`	string	yes	`--prompt`	Video description
`scene`	enum	no	`--scene`	`text-to-video`, `image-to-video`, `video-to-video`, `ad-video`
`provider`	string	no	`--provider`	Default `kie`
`model`	string	no	`--model`	Default `bytedance/seedance-2-mini` for text-to-video
`imageInput`	string[]	no	`--image-input`	Comma-separated URLs
`videoInput`	string[]	no	`--video-input`	Comma-separated URLs
`timeoutMs`	number	no	`--timeout`	Default 600000
`options`	object	no	—	Provider passthrough (API only)

Material search capabilities

Capability	Purpose
`media.materials.queries`	LLM query terms from script
`media.materials.search`	Search stock footage
`media.materials.import`	Download and store clips
`media.materials.auto`	End-to-end script → import

API responses

Success:

{
  "ok": true,
  "data": {},
  "meta": {
    "capabilityId": "ai.image.generate_and_wait",
    "execution": "sync"
  }
}

Error:

{
  "ok": false,
  "error": {
    "code": "EXECUTION_FAILED",
    "message": "human-readable message"
  }
}

Common errors

Symptom	Likely cause	Fix
HTTP 401	Missing or invalid API key	Check API Keys
Insufficient credits	Low account balance	Top up credits
Provider / `kie_api_key` errors	AI not configured server-side	Admin → Settings → AI
Upload failures	Storage not configured	Configure object storage before `--upload`
Material search failures	`backend_media` unavailable	Check media service configuration

Architecture

CLI and HTTP clients call /api/actions/* only — not Kie/Fal/Pexels directly
Same business logic as the web UI (/api/ai/generate, /api/media/materials/*)

On this page