Material Search | ModKie Docs

Search stock video clips from Pexels and Pixabay through the site API. This is stock footage search, not your personal media library (/api/media-library).

Configuration details: CLI & API Guide.

Flow

script → media.materials.queries → search terms
search terms → media.materials.search → candidate clips
selected clips → media.materials.import → stored assets
script → media.materials.auto → queries + search + import (one step)

Compose into a final video (media/compose/*) is not yet exposed as a capability.

Prerequisites

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

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

Commands

Generate search queries from script

pnpm ads material queries \
  --script "A barista making latte art in a cozy cafe" \
  --json

Search stock footage

pnpm ads material search \
  --queries "barista,coffee shop,latte art" \
  --source pexels \
  --aspect 9:16 \
  --json

Import selected materials

Save search results, pick items, then import:

{
  "materials": [
    { "provider": "pexels", "downloadUrl": "https://...", "id": "12345" }
  ]
}

pnpm ads material import --file selected-materials.json --json

Auto (script → search → import)

pnpm ads material auto \
  --script "Morning routine: coffee, commute, office desk" \
  --aspect 9:16 \
  --target-duration 30 \
  --json

CLI flags

Command	Flags
`queries`	`--script`, `--locale`, `--json`
`search`	`--queries` (comma-separated), `--source`, `--aspect`, `--min-duration`, `--limit`, `--json`
`import`	`--file` (JSON with `materials[]`), `--json`
`auto`	`--script`, `--aspect`, `--target-duration`, `--source`, `--min-duration`, `--limit`, `--json`

HTTP examples

Search:

curl -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -X POST https://modkie.com/api/actions/media.materials.search \
  -d '{"queries":["coffee shop","barista"],"source":"pexels","aspectRatio":"9:16"}'

Auto:

curl -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -X POST https://modkie.com/api/actions/media.materials.auto \
  -d '{"script":"Product demo for a fitness app","aspectRatio":"9:16","targetDuration":30}'

API endpoints

Capability	Method	URL
`media.materials.queries`	`POST`	`https://modkie.com/api/actions/media.materials.queries`
`media.materials.search`	`POST`	`https://modkie.com/api/actions/media.materials.search`
`media.materials.import`	`POST`	`https://modkie.com/api/actions/media.materials.import`
`media.materials.auto`	`POST`	`https://modkie.com/api/actions/media.materials.auto`

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

vs media library

Feature	Stock search (`media.materials.*`)	Media library (`/api/media-library`)
Source	Pexels / Pixabay	Your uploads and imports
Search	Semantic query terms	Paginated filter by kind/source
CLI	`ads material *`	Not yet exposed

On this page