# MomentIQ agent examples

Use this file when a human wants Claude, ChatGPT, Cursor, Replit, Lovable, or another AI builder to use MomentIQ.

MomentIQ is not a website the agent needs to manually click. MomentIQ is a media API, SDK, and remote MCP server the agent can call from backend code.

Important: the agent usually cannot connect MomentIQ automatically just because it can read the website. First ask whether the agent supports remote MCP tools. If yes, connect the MCP URL with a MomentIQ connector token. If no, ask the agent to use the REST API or SDK from backend code with a server-side API key. If it cannot use tools or backend code, use Moment Lab manually.

## Pick the right path

| User goal | Best path | What to give the agent |
| --- | --- | --- |
| “I just want to upload a video and get clips.” | Moment Lab | Send the user to `https://momentiq.dev/`. |
| “Build this into my app.” | API/SDK | Give the agent the SDK examples below and a server-side `MOMENTIQ_API_KEY`. |
| "Claude/ChatGPT should run media tools for me." | Remote MCP | Give the agent the MCP URL and a revocable connector token with a spend cap. |

For ChatGPT and Claude connector setup, prefer a revocable `MIQ_CONNECTOR_TOKEN` from the dashboard over a normal `MOMENTIQ_API_KEY`. Use normal API keys for backend/API integrations.

## Required environment variables

Put these in the server-side environment of the app or agent workspace.

```env
MOMENTIQ_API_KEY=miq_live_or_test_...
MOMENTIQ_API_BASE_URL=https://api.momentiq.dev
```

Never put `MOMENTIQ_API_KEY` in browser JavaScript, public prompts, screenshots, or shared docs.

## Remote MCP setup

Use this when the AI agent supports remote MCP tools.

```json
{
  "mcpServers": {
    "momentiq": {
      "url": "https://api.momentiq.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${MIQ_CONNECTOR_TOKEN}"
      }
    }
  }
}
```

Ask the MCP server for its own guide first:

```text
Call momentiq.get_agent_guide, then call momentiq.run_agent_diagnostics after authentication. Use the diagnostics output to decide whether to set a spend cap, create a billing link, wait for workers, or continue to job readiness.
```

### ChatGPT connector

Setup page: https://momentiq.dev/docs-chatgpt.html

```text
Use the MomentIQ.dev connector.
Do not create uploads or processing jobs yet.
First call momentiq.get_agent_guide.
Then call momentiq.list_endpoints and momentiq.list_workflows with live_safe_only=true.
If authenticated tools are available, call momentiq.run_agent_diagnostics and momentiq.get_account_limits.
Tell me whether my API key, free credits, billing status, worker health, and hard spend cap are ready for a small beta job.
```

### Claude connector

Setup page: https://momentiq.dev/docs-claude.html

```text
Use the MomentIQ.dev MCP connector if you have it available.
Do not create uploads or processing jobs yet.
First call momentiq.get_agent_guide.
Then call momentiq.plan_integration for this goal: find useful clips in a podcast video.
If authenticated tools are available, call momentiq.run_agent_diagnostics and momentiq.get_account_limits.
Tell me whether MomentIQ is ready, what key/billing/cap issues remain, and what the first live-safe test should be.
```

If the agent does not have MCP access yet, paste this first:

```text
Before using MomentIQ, check whether you have remote MCP/tool access.
If you do not have MCP access, tell me exactly how to connect the MomentIQ remote MCP server, or use MomentIQ's REST API from backend code.
Do not try to process media by clicking around the website.
Keep MOMENTIQ_API_KEY in server-side secrets only.
Estimate cost and check account limits before creating processing jobs.
```

Useful unauthenticated MCP discovery tools:

- `momentiq.get_agent_guide`
- `momentiq.list_endpoints`
- `momentiq.get_endpoint_schema`
- `momentiq.list_workflows`
- `momentiq.plan_integration`
- `momentiq.get_code_example`
- `momentiq.estimate_cost`

Useful authenticated MCP safety tools:

- `momentiq.run_agent_diagnostics`
- `momentiq.get_account_limits`
- `momentiq.set_spend_cap`
- `momentiq.get_usage_summary`
- `momentiq.create_billing_link`
- `momentiq.check_job_readiness`
- `momentiq.create_workflow_job`
- `momentiq.continue_workflow_job`
- `momentiq.get_job_result`
- `momentiq.list_jobs`
- `momentiq.regenerate_output_url`
- `momentiq.create_api_key`
- `momentiq.revoke_api_key`

## Live-safe first endpoints

Use these first in production/beta builds:

- `video/clip-window`
- `video/clip-near`
- `audio/detect-silence`
- `audio/detect-energy`

Treat other endpoints as preview until they are tested end-to-end for the account and media type.

## Prompt: build a no-code creator page

Paste this into an AI builder:

```text
Build a simple no-code MomentIQ page for content creators.

MomentIQ finds useful moments in video and audio.
Before using MomentIQ, check whether you have remote MCP/tool access.
If you do not have MCP access, use MomentIQ's REST API or SDK from backend code.
The page should let a user:
- choose the demo video or upload their own media;
- pick one MomentIQ tool or a workflow preset;
- see estimated usage cost before running;
- run the job;
- see queued/running/completed/failed states;
- preview the output when there is a video clip;
- download clips, JSON, or CSV/timestamp tables.

Use MomentIQ from backend code only.
Read MOMENTIQ_API_KEY from server-side environment variables.
Never expose the key in browser code.

Use signed uploads for local files:
1. Create a signed upload.
2. PUT the file bytes to the signed upload_url with upload_headers.
3. Use the returned media_url in readiness checks and jobs. Do not pass a local file path as media_url.

Start with these live-safe endpoints:
- video/clip-window
- video/clip-near
- audio/detect-silence
- audio/detect-energy

If remote MCP is available, connect to:
https://api.momentiq.dev/mcp

Use Authorization: Bearer ${MIQ_CONNECTOR_TOKEN}.
Show request_id and job_id on every error.
```

## MCP: plan an app integration from a vague user goal

Use this when the user says something like "I want Claude to make clips from my podcast" but does not know what to prompt or build.

```json
{
  "name": "momentiq.plan_integration",
  "arguments": {
    "goal": "Build a page where I upload a podcast video and get 3 good clips back",
    "target_platform": "lovable",
    "user_type": "creator",
    "media_source": "upload",
    "live_safe_only": true
  }
}
```

The tool returns the recommended endpoint chain, backend helpers, UI pieces, environment variables, safety checks, and a copy-ready prompt for the app builder.

## MCP: get copy-paste code examples

Use this after choosing an endpoint or workflow.

```json
{
  "name": "momentiq.get_code_example",
  "arguments": {
    "language": "node",
    "endpoint": "video/clip-window",
    "input_type": "file",
    "include_upload": true
  }
}
```

Supported languages: `node`, `python`, and `curl`. The examples keep `MOMENTIQ_API_KEY` server-side and include upload, job creation, polling, and result extraction when requested.

## Prompt: build a podcast clip finder

```text
Build a podcast clip finder with MomentIQ.

User flow:
1. Upload a podcast video or paste a media URL.
2. Analyze the audio for energetic/funny sections.
3. Find nearby silence for clean boundaries.
4. Render 3 downloadable video clips.

Use MomentIQ from backend code only.
Read MOMENTIQ_API_KEY from server-side environment variables.
Never expose the key in browser code.

For live beta reliability, start with:
- audio/detect-energy
- audio/detect-silence
- video/clip-window or video/clip-near

If audio/detect-laughter is marked stable for this account, use:
audio/detect-laughter -> audio/detect-silence -> video/clip-near

Show:
- upload progress;
- estimated cost;
- job status;
- clip preview;
- download button;
- timestamp table;
- JSON details behind a toggle;
- request_id/job_id on errors.
```

## Prompt: add MomentIQ to an existing app

```text
Add MomentIQ media intelligence to my app.

Create a backend module named momentiqService.
It should:
- read MOMENTIQ_API_KEY and MOMENTIQ_API_BASE_URL from server-side env vars;
- upload local files with signed uploads;
- create jobs;
- poll jobs with retry/backoff;
- return clean results to the frontend;
- never expose the API key to the browser.

Implement these helpers:
- createUpload(fileName, contentType, fileSize)
- uploadFile(file)
- createJob(endpoint, params)
- pollJob(job_id)
- clipWindow({ file, media_url, start, end })
- clipNear({ file, media_url, t, before, after, target_duration })
- detectEnergy({ file, media_url, settings })
- detectSilence({ file, media_url, settings })

Default base URL:
https://api.momentiq.dev

For long media, always use:
POST /v1/jobs
GET /v1/jobs/{job_id}
```

## Node SDK: clip a local video file

```js
const { MomentIQ } = require('./sdk/momentiq');

const miq = new MomentIQ({
  apiKey: process.env.MOMENTIQ_API_KEY,
  baseUrl: process.env.MOMENTIQ_API_BASE_URL || 'https://api.momentiq.dev',
});

async function main() {
  const clip = await miq.video.clipWindow({
    file: './podcast.webm',
    start: '00:01:00',
    end: '00:02:00',
  });

  console.log({
    job_id: clip.job_id,
    url: clip.url,
    result: clip.result,
  });
}

main().catch((err) => {
  console.error(err.code || 'momentiq_error', err.message);
  console.error(err.payload || err.job || '');
  process.exit(1);
});
```

## Node SDK: detect energy in local media

```js
const { MomentIQ } = require('./sdk/momentiq');

const miq = new MomentIQ({
  apiKey: process.env.MOMENTIQ_API_KEY,
});

async function main() {
  const energy = await miq.audio.detectEnergy({
    file: './podcast.webm',
    threshold: 0.75,
    min_segment_seconds: 2,
  });

  console.table(energy.result.segments || []);
}

main().catch(console.error);
```

## Raw HTTP: signed upload, job, polling

Use this when not using the SDK.

### 1. Create a signed upload

```bash
curl -X POST https://api.momentiq.dev/v1/uploads/presign \
  -H "Authorization: Bearer $MOMENTIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "podcast.webm",
    "content_type": "video/webm",
    "bytes": 12345678
  }'
```

Save:

- `upload.upload_url`
- `upload.upload_method`
- `upload.upload_headers`
- `upload.media_url`

### 2. PUT the file to the signed URL

```bash
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/webm" \
  --data-binary "@podcast.webm"
```

### 3. Create a worker job

```bash
curl -X POST https://api.momentiq.dev/v1/jobs \
  -H "Authorization: Bearer $MOMENTIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "video/clip-window",
    "media_url": "'"$MEDIA_URL"'",
    "start": 60,
    "end": 120,
    "settings": {
      "_run_on_worker": true
    }
  }'
```

### 4. Poll until completed or failed

```bash
curl https://api.momentiq.dev/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $MOMENTIQ_API_KEY"
```

Completed jobs include `job.result`. Clip jobs usually include a playable URL under one of:

- `job.result.url`
- `job.result.clip_url`
- `job.result.output_url`
- `job.result.output_file.url`

## MCP: plan and start a workflow

Use this when an agent wants to chain endpoints without guessing timestamps too early.

```json
{
  "name": "momentiq.create_workflow_job",
  "arguments": {
    "workflow_id": "energy_to_clip",
    "media_url": "https://example.com/podcast.mp4",
    "media_seconds": "00:10:00"
  }
}
```

That returns a plan, per-step estimates, and the next safe action. To queue only the first step:

```json
{
  "name": "momentiq.create_workflow_job",
  "arguments": {
    "workflow_id": "energy_to_clip",
    "media_url": "https://example.com/podcast.mp4",
    "media_seconds": "00:10:00",
    "execute_first_step": true
  }
}
```

Do not queue later clip steps until the agent has inspected the earlier audio/timeline results and chosen real timestamps.

## MCP: continue a workflow after a job finishes

Use this after the first workflow job completes. It reads the previous job result, suggests the next step, and can queue only that next step.

```json
{
  "name": "momentiq.continue_workflow_job",
  "arguments": {
    "workflow_id": "energy_to_clip",
    "previous_job_id": "job_123"
  }
}
```

If the suggested next step is correct, queue it:

```json
{
  "name": "momentiq.continue_workflow_job",
  "arguments": {
    "workflow_id": "energy_to_clip",
    "previous_job_id": "job_123",
    "execute_next_step": true
  }
}
```

Repeat: poll `momentiq.get_job`, then call `momentiq.continue_workflow_job` again. This keeps agents from blindly rendering clips before they know the right timestamps.

## MCP: check a job before spending credits

First inspect the endpoint schema if the agent is unsure about required params:

```json
{
  "name": "momentiq.get_endpoint_schema",
  "arguments": {
    "endpoint": "video/clip-window"
  }
}
```

Use this before `momentiq.create_job`.

```json
{
  "name": "momentiq.check_job_readiness",
  "arguments": {
    "endpoint": "audio/detect-energy",
    "media_url": "https://example.com/podcast.mp4",
    "media_seconds": "00:10:00"
  }
}
```

The response tells the agent whether the request is ready, what is missing, whether the endpoint is preview-only, what the estimate is, and whether billing or spend caps block the job.

## MCP: refresh an expired output link

Use this when a completed job has an R2-backed output but the signed clip/frame URL has expired.

```json
{
  "name": "momentiq.regenerate_output_url",
  "arguments": {
    "job_id": "job_123",
    "expires_in_seconds": 86400
  }
}
```

This does not rerun media processing and should not create another billable job. It only signs fresh URLs for stored outputs the account owns.

## What the frontend should receive

The frontend should receive clean, non-secret data from your backend:

```json
{
  "job_id": "job_123",
  "status": "completed",
  "endpoint": "video/clip-window",
  "result_url": "https://...",
  "segments": [],
  "price_usd": 0.035,
  "request_id": "req_123"
}
```

The frontend should not receive:

- the full MomentIQ API key;
- signed upload secrets after upload;
- internal worker secrets;
- unrestricted admin URLs.

## Cost and safety checklist

Before letting an AI agent run real jobs:

- Use a test key first.
- Create a scoped key for the agent.
- Set a hard monthly spend cap.
- Call `momentiq.get_account_limits` to show free credits, current usage, spend cap, and alerts.
- Call `momentiq.set_spend_cap` if the user has not set a safe cap yet.
- Call `momentiq.check_job_readiness` before `momentiq.create_job`.
- Call `momentiq.create_workflow_job` for multi-step workflows instead of launching several jobs blindly.
- Call `momentiq.continue_workflow_job` after each completed workflow job so MomentIQ can suggest the next timestamp-aware step.
- Call `momentiq.estimate_cost` before creating paid jobs.
- If a job returns `billing_required`, call `momentiq.create_billing_link` and send the user to Stripe Checkout or the dashboard billing fallback.
- If an output URL expires, call `momentiq.regenerate_output_url` before rerunning any paid processing.
- Show estimated cost before running.
- Poll jobs instead of retrying job creation.
- Do not bill or retry failed jobs blindly.
- Revoke unused keys after experiments.

## Troubleshooting

| Error | Meaning | What the agent should do |
| --- | --- | --- |
| `missing_api_key` | No key was sent. | Ask the user to set `MOMENTIQ_API_KEY` server-side. |
| `invalid_api_key` | Key is wrong or revoked. | Ask the user to create a new key. |
| `billing_required` | Free credits are gone and billing is not active. | Call `momentiq.create_billing_link`, then send the user to the returned URL. |
| `invalid_media_url` | URL is missing, expired, or unreachable. | Re-upload the file or ask for a valid public/signed URL. |
| `unsupported_file_type` | Format is not supported. | Convert media or upload mp4, mov, webm, mp3, wav, m4a, aac, or ogg. |
| `processing_failed` | Worker could not complete the job. | Show request_id/job_id and error details. |

## One-sentence explanation for users

MomentIQ gives your AI app media tools: upload video/audio, find useful timestamps, render clips, and return downloadable results without making your agent build FFmpeg workflows from scratch.