Image Generation | ModKie Docs

Generate web graphics and logos through the site API — no web UI required.

Configuration details: CLI & API Guide.

Prerequisites

Create a key at Settings → API Keys (sk-...)
Configure the CLI:

pnpm ads login --host https://modkie.com --api-key sk-xxxxxxxx

Or environment variables:

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

Commands

Generate and wait

pnpm ads image generate \
  --preset logo \
  --prompt "minimal wordmark, flat vector, white background" \
  --out ./public/brand/logo.png

Optional: --timeout 300000 (milliseconds, default 180000).

Generate and upload to media library

pnpm ads image generate \
  --preset web-hero \
  --prompt "SaaS dashboard hero, clean lighting, no text" \
  --out ./public/marketing/hero.png \
  --upload \
  --json

--json output example:

{
  "taskId": "...",
  "status": "success",
  "imageUrl": "https://...",
  "localPath": "./public/marketing/hero.png",
  "url": "https://cdn.../uploaded.png"
}

Query a task

pnpm ads image query --task-id <uuid> --json

List capabilities / schema

pnpm ads actions list
pnpm ads actions schema ai.image.generate_and_wait

Presets

preset	Aspect	Use case
`logo`	1:1	Logo, app icon
`web-hero`	16:9	Homepage / landing hero
`web-section`	4:3	Feature section art
`og-image`	16:9	Social share (no text overlay)

CLI flags vs API fields

Flag	API field
`--prompt`	`prompt`
`--preset`	`preset`
`--scene`	`scene`
`--provider`	`provider`
`--model`	`model`
`--aspect`	`aspectRatio`
`--resolution`	`resolution`
`--timeout`	`timeoutMs`
`--upload`	triggers `storage.upload_image`

API-only fields: imageInput, options, workspaceId.

HTTP examples

Generate (blocking):

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"}'

Image-to-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 '{
    "prompt": "same style portrait",
    "scene": "image-to-image",
    "imageInput": ["https://example.com/reference.png"],
    "timeoutMs": 300000
  }'

Async create + poll:

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

API endpoints

Method	URL
`GET`	`https://modkie.com/api/actions`
`GET`	`https://modkie.com/api/actions/ai.image.generate_and_wait/schema`
`POST`	`https://modkie.com/api/actions/ai.image.generate_and_wait`
`POST`	`https://modkie.com/api/actions/ai.image.query`

Auth: Authorization: Bearer sk-xxx or X-Api-Key: sk-xxx

On this page