Letsgen
← Lets Gen MCP

Developer documentation · English

Reference reviewed 6 November 2026

Lets Gen MCP documentation

Generate images, video, character portraits, lip-sync video, music and speech from an MCP client. Connect with OAuth, reuse your private media, set a Gem spending limit and retrieve durable generation results.

01 / Reference

Connection & authorization

Add this remote Streamable HTTP server to an MCP client that supports browser-based OAuth. There is no API key to copy: the client starts a standard OAuth sign-in and stores its own access and refresh tokens.

Server URL
https://mcp.letsgen.app/mcp

Start the sign-in from the client. An authorization URL forwarded from another machine will not complete, because the request is bound to that client's PKCE challenge and loopback callback.

Claude Code
claude mcp add --transport http letsgen https://mcp.letsgen.app/mcp
Codex CLI
codex mcp add letsgen --url https://mcp.letsgen.app/mcp
codex mcp login letsgen
Cursor · .cursor/mcp.json
{
  "mcpServers": {
    "letsgen": {
      "url": "https://mcp.letsgen.app/mcp"
    }
  }
}
VS Code · .vscode/mcp.json
{
  "servers": {
    "letsgen": {
      "type": "http",
      "url": "https://mcp.letsgen.app/mcp"
    }
  }
}
ChatGPT connector
Settings → Connectors → Advanced → enable developer mode
Create connector → https://mcp.letsgen.app/mcp

The client performs OAuth Authorization Code with S256 PKCE and manages access and refresh tokens. Account cookies and Lets Gen API keys are not substitutes for an OAuth access token.

ScopeAccess
mcp:readRequired for the MCP connection: account, capability, owned-media and generation reads.
mcp:generateAdditional permission to import media or call any of the six Create tools. Request it together with mcp:read.
mcp:canvas:writeAdditional permission to update owned Canvas projects. Read access is account-wide for owned projects; mcp:generate does not grant Canvas editing.

OAuth discovery is available at the protected-resource metadata URL. Its authorization server is Lets Gen. Access tokens are bound to the MCP resource URL; tokens for another environment are not interchangeable.

The server accepts POST /mcp. Let the SDK negotiate the protocol, initialize the connection and supply protocol headers. The adapter supports standard 2025-11-25 initialization and 2026-07-28 discovery. The JSON examples below are tools/call parameters after initialization, rather than complete HTTP requests.

Manage or revoke clients on MCP connections. Revocation blocks subsequent requests. Outputs and imported references stay private to the connected personal account unless you publish them separately in Lets Gen.

02 / Reference

17 public tools

Call list_generation_capabilities before choosing generation inputs. Its inputs, options and model-specific models[].capabilities describe current accepted values. Discovery does not promise that every model will be available to your account when you submit.

connect_canvas_project

mcp:read

Read an owned Canvas project and its editing guide before changing its graph.

Parameters
projectId: nonempty string (≤160 characters).
Result
{ project, cursor, guide, canvasUrl }. guide includes workflow instructions and graphSchema. This does not create a session, approve storyboard images or start generation.

get_canvas_project

mcp:read

Read the current owned Canvas graph, revision and generation statuses.

Parameters
projectId: nonempty string (≤160 characters).
Result
{ project, cursor, canvasUrl }. Use the current revision for updates and cursor for waiting.

update_canvas_project

mcp:canvas:write

Save an owned Canvas graph using revision compare-and-swap, preserving unrelated work.

Parameters
projectId: nonempty string (≤160 characters); revision: integer ≥0; graph: object matching the schema returned by connect_canvas_project; title?: string (1–120 characters).
Result
{ project, cursor, canvasUrl }. On a stale revision, reread and reconcile instead of resubmitting a stale graph with a newer revision. Generation remains a creator-reviewed action in Canvas.

wait_canvas_project

mcp:read

Wait for graph-revision or generation-status changes without starting or recovering generation.

Parameters
projectId: nonempty string (≤160 characters); cursor: string (1–128 characters); timeoutMs?: integer 0–20000 (default 15000).
Result
{ project, cursor, changed, canvasUrl }. changed:false means the wait timed out, not that generation completed. Status changes can occur without a graph revision change.

list_generation_capabilities

mcp:read

Discover the six generators, their current input definitions and model-specific options.

Parameters
{} — no arguments.
Result
{ capabilities: [...] }. Each entry includes capability, appId, outputKind, availability, inputs and options. Image/video entries also include models.

get_account

mcp:read

Read your Gem balance and subscription plan.

Parameters
{} — no arguments.
Result
{ gemBalance: number, plan: string, generationAvailable: boolean }. generationAvailable reflects a positive balance; Create still checks price, model access and account eligibility.

list_media_assets

mcp:read

Browse ready, visible media owned by the connected account.

Parameters
kind?: image | video | audio; cursor?: string (≤500 characters); limit?: integer 1–50 (default 24).
Result
{ assets: [...], nextCursor: string | null }. Each asset has id, kind, state and media metadata. Hidden one-shot imports are not listed; retain their returned id.

get_media_asset

mcp:read

Read one owned asset before using it as a reference.

Parameters
assetId: nonempty string (≤160 characters).
Result
{ asset: {...} }. The asset identifier is asset.id; check kind and state === ready. Available content and preview links depend on the asset.

import_media_from_url

mcp:generate

Import one public HTTPS file as private, temporary one-shot media.

Parameters
url: valid URL (≤2048 characters); kind: image | video | audio; originalName?: string (1–120 characters).
Result
{ asset: {...} }. Keep asset.id for subsequent requests. Import is a write operation and has no idempotencyKey parameter.

list_generations

mcp:read

Browse private generation history, including pending work.

Parameters
capability?: one of the six capability keys below; kind?: image | video | audio; cursor?: string (≤500 characters); limit?: integer 1–50 (default 20).
Result
{ generations: [...], nextCursor: string | null }. History entries use the generation shape below, without remainingGems.

get_generation

mcp:read

Poll a generation and retrieve ready outputs and current Gem accounting.

Parameters
generationId: nonempty string (≤160 characters).
Result
{ generation: {...} }. Includes generationId, capability, status, gemCost, settledGems, remainingGems, timestamps, error and outputs.

create_image_generation

mcp:generate

Generate images from a prompt and optional owned references.

Parameters
request: object; idempotencyKey: string; maxGemCost?: integer ≥0. See the shared Create envelope below.
Result
{ generation: {...}, created: boolean }. Capability: image_generation; output kind: image.

prompt is required (≤20,000 characters). referenceImages holds up to ten owned image IDs, subject to the selected model's lower limit. outputCount is 1–4. Some editing models require sourceImage. Use current model-specific input, ratio and resolution options.

create_video_generation

mcp:generate

Generate video from text or an owned starting image.

Parameters
request: object; idempotencyKey: string; maxGemCost?: integer ≥0.
Result
{ generation: {...}, created: boolean }. Capability: video_generation; output kind: video.

For image-to-video, sourceImage is an owned ready image ID, not a URL. Choose a model whose capabilities.inputs includes first-frame. duration is a string such as "6"; ratio, resolution and audio are model-specific. A supplied sourceImage determines image-to-video mode.

create_character_image

mcp:generate

Generate an original character portrait; this does not create a chat Character.

Parameters
request: object; idempotencyKey: string; maxGemCost?: integer ≥0.
Result
{ generation: {...}, created: boolean }. Capability: character_image; output kind: image.

appearance is required (≤2,000 characters); outputCount is 1–4. referenceImages accepts at most one owned image. Reference images and animaLoras cannot be combined; without a reference, a compatible style selection is required.

create_lip_sync_video

mcp:generate

Animate an owned image or existing Character using owned audio.

Parameters
request: object; idempotencyKey: string; maxGemCost?: integer ≥0.
Result
{ generation: {...}, created: boolean }. Capability: lip_sync_video; output kind: video.

drivenAudio is required. Provide sourceImage or an existing character ID. Choose model from talking-head-models. Infinitalk: up to 15s, 480p/720p. OmniHuman 2.0: MP3/WAV under 15 MB, 4–300s, fixed 720p, 60 Gems per started audio second.

create_music_generation

mcp:generate

Generate music from a prompt, optionally using an owned cover audio reference.

Parameters
request: object; idempotencyKey: string; maxGemCost?: integer ≥0.
Result
{ generation: {...}, created: boolean }. Capability: music_generation; output kind: audio.

Inputs depend on musicMode. Simple mode uses a song-idea prompt (up to 3,000 characters). Advanced mode requires style and title, with prompt carrying lyrics (up to 5,000 characters) when vocals are requested. coverAudio is optional; sound-effect mode has separate options. Discover accepted fields and option keys first.

create_voice_speech

mcp:generate

Generate speech using an existing authorized voice or a consented owned reference recording.

Parameters
request: object; idempotencyKey: string; maxGemCost?: integer ≥0.
Result
{ generation: {...}, created: boolean }. Capability: voice_speech; output kind: audio.

prompt is required (≤2,000 characters). Use a visible voiceProfileId, or provide an owned referenceAudio with referenceConsent: confirmed and no voiceProfileId. Reference recordings must pass voice-reference validation. Model-specific speech tuning fields are described by discovery. MCP does not manage or list voice profiles.

The catalog contains four Canvas tools, six generation tools and seven account, discovery, media and history tools. MCP does not expose publishing, deletion, checkout, Character profile creation or voice-profile management. create_character_image creates portraits; create_voice_speech uses an authorized voice or an owned, consented reference recording.

For Canvas, connect and read its graph schema before updating. Editing does not start paid generation or approve storyboard images: the creator reviews and generates in Canvas. See the Canvas handbook returned by the connection guide.

03 / Reference

Create parameters

All six Create tools use the same three top-level parameters:

ParameterType & requirementMeaning
requestRequired objectValues for the selected generator. Do not wrap them in draft or send an appId or definitionVersion.
idempotencyKeyRequired string, 12–160 charactersLetters, digits, ., _, : and -. Keep the same key and request values when retrying one logical generation.
maxGemCostOptional integer ≥0Maximum total Gems approved for this Create call. The example requires an explicit limit. Omitting it removes this caller-provided price cap.

Asset inputs such as sourceImage, drivenAudio and referenceImages use owned asset IDs, not file bytes or media URLs. Import a public URL first. Selection options such as duration are strings; outputCount is an integer and prompt optimization fields are booleans.

Generator request field reference

These fields come from the shared built-in generator definitions. Conditional fields only apply when supported by the selected model or workflow; live capability discovery remains authoritative. Internal routing controls are omitted.

create_image_generation

FieldDefinition
experience{"type":"option-group","key":"experience","capability":"image-experience"}
prompt{"type":"prompt","key":"prompt","required":true,"maxLength":20000}
posePreset{"type":"pose-preset","key":"posePreset"}
magicPrompt{"type":"magic-prompt","key":"magicPrompt","defaultValue":true}
references{"type":"reference-picker","key":"references","kinds":["character","action","outfit","scene"]}
referenceImages{"type":"asset-uploader-list","key":"referenceImages","required":false,"kind":"image","minCount":0,"maxCount":16,"purpose":"Visual references (each model has its own limit)"}
style{"type":"style-dialog","key":"style","favorites":true}
effectTemplate{"type":"option-group","key":"effectTemplate","capability":"effect-templates"}
promptRecipe{"type":"option-group","key":"promptRecipe","capability":"prompt-recipes"}
model{"type":"model-selector","key":"model","defaultModelKey":"flux-schnell"}
sourceImage{"type":"image-uploader","key":"sourceImage","required":true,"purpose":"Source image to edit","visibleWhen":{"key":"model","equals":"ideogram-v4.5-edit"}}
editPrecision{"type":"option-group","key":"editPrecision","capability":"ideogram-edit-precision","visibleWhen":{"key":"model","equals":"ideogram-v4.5-edit"}}
background{"type":"option-group","key":"background","capability":"gpt-image-background","visibleWhen":{"key":"model","in":["lets-gen-max","gpt-image-2","qwen-image-2-1"]}}
variant{"type":"option-group","key":"variant","capability":"gpt-image-2.5-variants","visibleWhen":{"key":"model","equals":"gpt-image-2.5"}}
outputFormat{"type":"option-group","key":"outputFormat","capability":"image-output-formats","visibleWhen":{"key":"model","equals":"gpt-image-2.6"}}
complexity{"type":"option-group","key":"complexity","capability":"image-complexity","visibleWhen":{"key":"model","equals":"gpt-image-2.6"}}
animaLoras{"type":"anima-style-dialog","key":"animaLoras","maxSelections":8,"visibleWhen":{"key":"model","equals":"anima-turbo1.1"}}
xlStyle{"type":"xl-style-dialog","key":"xlStyle","maxSelections":1,"visibleWhen":{"key":"model","equals":"letsgen-art-pro"}}
xlBaseModel{"type":"option-group","key":"xlBaseModel","capability":"xl-base-models","visibleWhen":{"key":"model","equals":"letsgen-xl"}}
xlLora{"type":"option-group","key":"xlLora","capability":"xl-compatible-loras","visibleWhen":{"key":"model","equals":"letsgen-xl"}}
xlLoraWeight{"type":"number","key":"xlLoraWeight","min":0.05,"max":2,"step":0.05,"visibleWhen":{"key":"model","equals":"letsgen-xl"}}
ratio{"type":"option-group","key":"ratio","capability":"image-ratios"}
resolution{"type":"option-group","key":"resolution","capability":"image-resolutions"}
quality{"type":"option-group","key":"quality","capability":"image-quality","visibleWhen":{"key":"model","in":["ideogram-v4.5-edit"]}}
mjVersion{"type":"option-group","key":"mjVersion","capability":"midjourney-version","visibleWhen":{"key":"model","equals":"midjourney"}}
stylize{"type":"number","key":"stylize","min":0,"max":1000,"step":1,"visibleWhen":{"key":"model","equals":"midjourney"}}
chaos{"type":"number","key":"chaos","min":0,"max":100,"step":1,"visibleWhen":{"key":"model","equals":"midjourney"}}
weird{"type":"number","key":"weird","min":0,"max":3000,"step":1,"visibleWhen":{"key":"model","equals":"midjourney"}}
outputCount{"type":"output-count","key":"outputCount","min":1,"max":4}
negativePrompt{"type":"negative-prompt","key":"negativePrompt","maxLength":1000}

create_video_generation

FieldDefinition
mode{"type":"option-group","key":"mode","capability":"animation-input-mode"}
posePreset{"type":"pose-preset","key":"posePreset"}
sourceImage{"type":"image-uploader","key":"sourceImage","required":false,"purpose":"Starting frame","visibleWhen":{"key":"mode","in":["image-to-video"]}}
referenceVideo{"type":"video-uploader","key":"referenceVideo","required":false,"purpose":"Reference video (2–15 seconds)"}
referenceImages{"type":"asset-uploader-list","key":"referenceImages","required":false,"kind":"image","minCount":0,"maxCount":15,"purpose":"Visual references","visibleWhen":{"key":"mode","equals":"text-to-video"}}
referenceVideos{"type":"asset-uploader-list","key":"referenceVideos","required":false,"kind":"video","minCount":0,"maxCount":5,"purpose":"Reference videos (up to 5, 15 seconds total)"}
referenceAudios{"type":"asset-uploader-list","key":"referenceAudios","required":false,"kind":"audio","minCount":0,"maxCount":5,"purpose":"Reference audio clips (up to 5, 15 seconds total)"}
prompt{"type":"prompt","key":"prompt","required":false,"maxLength":30000}
character{"type":"character-picker","key":"character","allowCreate":true}
references{"type":"reference-picker","key":"references","kinds":["character"]}
style{"type":"style-dialog","key":"style","favorites":true}
model{"type":"model-selector","key":"model","defaultModelKey":"grok-imagine"}
duration{"type":"option-group","key":"duration","capability":"video-durations"}
ratio{"type":"option-group","key":"ratio","capability":"video-ratios"}
resolution{"type":"option-group","key":"resolution","capability":"video-resolutions"}
endFrame{"type":"image-uploader","key":"endFrame","required":false,"purpose":"Ending frame","visibleWhen":{"capability":"video-end-frame"}}
audio{"type":"option-group","key":"audio","capability":"video-audio"}

create_character_image

FieldDefinition
appearance{"type":"prompt","key":"appearance","required":true,"maxLength":2000}
optimization{"type":"magic-prompt","key":"optimization","defaultValue":true}
animaLoras{"type":"anima-style-dialog","key":"animaLoras","maxSelections":4}
referenceImages{"type":"asset-uploader-list","key":"referenceImages","required":false,"kind":"image","minCount":0,"maxCount":1,"purpose":"Single-character identity reference"}
outputCount{"type":"output-count","key":"outputCount","min":1,"max":4}
chips{"type":"reference-picker","key":"chips","kinds":["character","action","outfit","scene"]}

create_lip_sync_video

FieldDefinition
sourceImage{"type":"image-uploader","key":"sourceImage","required":false,"purpose":"Speaker image"}
character{"type":"character-picker","key":"character","allowCreate":false}
model{"type":"option-group","key":"model","capability":"talking-head-models"}
drivenAudio{"type":"audio-uploader","key":"drivenAudio","required":true,"recordable":true}
resolution{"type":"option-group","key":"resolution","capability":"talking-head-resolutions"}

create_music_generation

FieldDefinition
musicMode{"type":"option-group","key":"musicMode","capability":"music-mode"}
soundVersion{"type":"option-group","key":"soundVersion","capability":"sound-versions","visibleWhen":{"key":"musicMode","equals":"sound-effect"}}
soundType{"type":"option-group","key":"soundType","capability":"sound-types","visibleWhen":{"key":"musicMode","equals":"sound-effect"}}
bpm{"type":"number","key":"bpm","min":1,"max":300,"step":1,"visibleWhen":{"key":"musicMode","equals":"sound-effect"}}
musicalKey{"type":"option-group","key":"musicalKey","capability":"sound-keys","visibleWhen":{"key":"musicMode","equals":"sound-effect"}}
audioFormat{"type":"option-group","key":"audioFormat","capability":"sound-formats","visibleWhen":{"key":"musicMode","equals":"sound-effect"}}
prompt{"type":"prompt","key":"prompt","required":false,"maxLength":5000}
coverAudio{"type":"audio-uploader","key":"coverAudio","required":false,"recordable":false}
instrumental{"type":"option-group","key":"instrumental","capability":"music-instrumental"}
style{"type":"prompt","key":"style","required":true,"maxLength":1000,"visibleWhen":{"key":"musicMode","equals":"advanced"}}
title{"type":"prompt","key":"title","required":true,"maxLength":80,"visibleWhen":{"key":"musicMode","equals":"advanced"}}
negativeTags{"type":"prompt","key":"negativeTags","required":false,"maxLength":200,"visibleWhen":{"key":"musicMode","equals":"advanced"}}
vocalGender{"type":"option-group","key":"vocalGender","capability":"music-vocal-gender","visibleWhen":{"key":"musicMode","equals":"advanced"}}
duration{"type":"option-group","key":"duration","capability":"music-duration","visibleWhen":{"key":"musicMode","equals":"advanced"}}

create_voice_speech

FieldDefinition
prompt{"type":"prompt","key":"prompt","required":true,"maxLength":2000}
voiceProfileId{"type":"voice-picker","key":"voiceProfileId","required":false}
referenceAudio{"type":"audio-uploader","key":"referenceAudio","required":false,"recordable":true}
referenceConsent{"type":"option-group","key":"referenceConsent","capability":"voice-reference-consent"}
model{"type":"model-selector","key":"model","defaultModelKey":"letsgen-voice"}
speed{"type":"number","key":"speed","min":0.5,"max":2,"step":0.1}
volume{"type":"number","key":"volume","min":-6,"max":6,"step":1}
temperature{"type":"number","key":"temperature","min":0,"max":1,"step":0.1}

For video, choose a compatible combination from models[].capabilities: inputs, aspectRatios, durations, resolutions, audio and audioRequired. Union lists under options do not mean every combination works for every model.

04 / Reference

Results & polling

Read machine-readable data from reply.structuredContent.result. A successful tool result also contains a short text summary; it is not the generation state. Business errors use isError: true and structuredContent.error. JSON-RPC and OAuth failures may instead be transport or protocol errors.

Illustrative accepted Create result
{
  "content": [
    {
      "type": "text",
      "text": "Generation accepted. Poll get_generation until it reaches a terminal state."
    }
  ],
  "structuredContent": {
    "result": {
      "generation": {
        "generationId": "run_example_video",
        "capability": "video_generation",
        "status": "queued",
        "gemCost": 100,
        "settledGems": 0,
        "remainingGems": 900,
        "createdAt": "2026-10-23T08:00:00.000Z",
        "updatedAt": "2026-10-23T08:00:00.000Z",
        "completedAt": null,
        "error": null,
        "outputs": [
          {
            "index": 0,
            "status": "pending",
            "asset": null
          }
        ]
      },
      "created": true
    }
  }
}

All example IDs, timestamps, prices, balances and media URLs on this page are illustrative fixtures, not a live generation transcript or a price promise.

Create returns a durable generationId immediately. Poll get_generation using that ID. Suggested client polling: once every five seconds with a ten-minute local deadline; these are example client settings, not server completion guarantees.

Poll parameters
{
  "name": "get_generation",
  "arguments": {
    "generationId": "run_example_video"
  }
}
  • In progress: created, reserved, queued, processing.
  • Terminal: succeeded, partial, failed, cancelled. Stop polling in all four terminal states.
  • Use only outputs with status === "succeeded" and a non-null asset. partial can contain both usable and failed outputs.
Illustrative structuredContent.result.generation after completion
{
  "generationId": "run_example_video",
  "capability": "video_generation",
  "status": "succeeded",
  "gemCost": 100,
  "settledGems": 100,
  "remainingGems": 900,
  "createdAt": "2026-10-23T08:00:00.000Z",
  "updatedAt": "2026-10-23T08:01:00.000Z",
  "completedAt": "2026-10-23T08:01:00.000Z",
  "error": null,
  "outputs": [
    {
      "index": 0,
      "status": "succeeded",
      "asset": {
        "assetId": "asset_example_video",
        "kind": "video",
        "mimeType": "video/mp4",
        "width": 854,
        "height": 480,
        "durationMs": 6000,
        "url": "https://media.letsgen.app/example-video.mp4"
      }
    }
  ]
}

Generation outputs expose asset.assetId and a ready media url. Asset-list, asset-detail and import tools return asset.id instead. Pass either identifier as sourceImage when it is an owned image. Treat direct media links as share-sensitive capability URLs and observe account retention limits.

05 / Reference

Gems & spending limits

The platform validates the request, checks ownership and eligibility, calculates its current price, and reserves Gems before starting a generation. Pricing depends on the model and settings, including output count, duration, resolution and audio where applicable.

  • gemCost is the quoted total for the accepted run. settledGems is the amount settled so far; it can be zero while work is pending.
  • remainingGems is the current account balance returned with Create and get_generation. Generation-history entries omit it.
  • A final run settles successful outputs and releases unused reservations for failed or cancelled outputs. Check final status and settledGems, including partial outcomes.
  • Read tools do not create a new generation reservation. Media import does not itself reserve generation Gems; storage and retention restrictions still apply.

There is no separate public quote tool. Image-model creditCost metadata is guidance, not a guaranteed total for an arbitrary request. Use an approved maxGemCost; if the authoritative price exceeds it, Create returns PRICE_CHANGED without charging for that rejected submission.

Illustrative over-budget result
{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "The current price is above the requested Gem limit. Nothing was charged."
    }
  ],
  "structuredContent": {
    "error": {
      "code": "PRICE_CHANGED",
      "message": "The current price is above the requested Gem limit. Nothing was charged.",
      "retryable": false
    }
  }
}

Repeating the same key and equivalent request returns the same generation with created: false, rather than purchasing another run. Changing the request under that key produces IDEMPOTENCY_CONFLICT. A new key represents a new billable request; never generate one automatically to recover from an uncertain response.

Read account pricing and the Gems guides for purchasing and balance information. The values in this reference are not a fixed Gem or currency tariff.

06 / Reference

Complete image-to-video walkthrough

Start with an image you own, create one video, and keep the generation ID until it finishes. You need both mcp:read and mcp:generate, an eligible account with enough Gems, and an explicitly approved spending limit.

  1. Discover the account and video inputs

    Call get_account and list_generation_capabilities. Find video_generation, check its availability and select a model with first-frame in capabilities.inputs.

  2. Get an owned starting-frame ID

    Use list_media_assets with kind: "image", then get_media_asset to confirm it is ready. Alternatively import a direct public HTTPS image:

    Import parameters · example URL must be replaced
    {
      "name": "import_media_from_url",
      "arguments": {
        "url": "https://example.com/your-image.png",
        "kind": "image",
        "originalName": "starting-frame.png"
      }
    }

    Save structuredContent.result.asset.id. Import downloads must be public HTTPS, without credentials or a custom port; redirects and destination addresses are checked. Limits are 20 MiB for images, 25 MiB for audio and 64 MiB for video, with additional file-type and inspection checks. A share-page URL or local filesystem path is not a media file.

    One-shot imports are temporary, hidden from the regular library list, and currently use a seven-day retention period. Keep the returned ID. Import has no idempotency key; repeating it may create another asset.

  3. Create once, within the approved budget

    Use the imported or selected ID as request.sourceImage. The following model settings are an example supported by the current source catalog; rediscover live options before submitting. The 120-Gem cap is an illustrative limit, not a price quote.

    Create parameters
    {
      "name": "create_video_generation",
      "arguments": {
        "request": {
          "mode": "image-to-video",
          "sourceImage": "asset_example_image",
          "model": "grok-imagine",
          "prompt": "A gentle breeze moves the leaves. The camera slowly pushes in. Preserve the subject and composition.",
          "duration": "6",
          "ratio": "16:9",
          "resolution": "480p",
          "audio": "on"
        },
        "idempotencyKey": "example-video-20261023-001",
        "maxGemCost": 120
      }
    }
  4. Poll the returned generation ID

    Read structuredContent.result.generation.generationId. Call get_generation until a terminal state. Keep the same generation ID after a polling failure; do not submit another Create.

  5. Use the completed video

    Find a successful output whose asset.kind is video. Its asset.url is the delivery link and asset.assetId is the owned asset ID. Inspect gemCost, settledGems and remainingGems for accounting.

07 / Reference

Runnable Node.js example

This example discovers a compatible video model, imports or checks an image, creates one video with a Gem cap, and polls to a terminal result. The same exported function can use an already connected MCP SDK client whose OAuth provider handles browser consent and refresh.

Download letsgen-image-to-video.mjs ↓
Install the client SDK
npm install @modelcontextprotocol/sdk@1.30.0

For the standalone CLI, supply an OAuth access token issued for this production MCP resource through an authorized OAuth client. It is not an API key. The fixed-token example does not perform browser login or token refresh; use an SDK authProvider for interactive applications. Keep tokens out of source files, URLs and logs.

Environment inputs · running this can spend Gems
# Supply the OAuth token through your secure environment, not this file.
# LETSGEN_ACCESS_TOKEN must already be set.
export LETSGEN_ASSET_ID='YOUR_READY_OWNED_IMAGE_ID'
# Or set LETSGEN_IMAGE_URL instead of LETSGEN_ASSET_ID.
export LETSGEN_MAX_GEMS='YOUR_APPROVED_INTEGER_LIMIT'
export LETSGEN_IDEMPOTENCY_KEY='YOUR_UNIQUE_GENERATION_KEY'
# Optional: LETSGEN_VIDEO_MODEL, chosen from capability discovery.
node letsgen-image-to-video.mjs

The script prints a prepared checkpoint before Create and an accepted checkpoint with the generation ID. Save them. To recover from an uncertain Create response, reuse the exact saved arguments; reimporting a URL produces a different asset ID and can cause an idempotency conflict. A local polling timeout or closing the client does not cancel the server-side job.

Read the complete example source
letsgen-image-to-video.mjs
/**
 * Lets Gen MCP image-to-video example. Node.js 22+.
 * Install @modelcontextprotocol/sdk@1.30.0 to use the command-line entry point.
 * Running the example can import media and spend Gems up to maxGemCost.
 * No retries of imports or Create are performed automatically.
 */
export async function runImageToVideo(client, options, dependencies = {}) {
  const { assetId, imageUrl, maxGemCost, idempotencyKey, modelKey, signal } = options;
  if (Boolean(assetId) === Boolean(imageUrl)) throw new Error("Provide exactly one owned assetId or public imageUrl.");
  if (!Number.isSafeInteger(maxGemCost) || maxGemCost < 0) throw new Error("Provide an approved integer maxGemCost of zero or more.");
  if (typeof idempotencyKey !== "string" || !/^[A-Za-z0-9._:-]{12,160}$/.test(idempotencyKey)) {
    throw new Error("Provide an idempotencyKey of 12–160 letters, digits, dots, underscores, colons or hyphens.");
  }
  const pollIntervalMs = options.pollIntervalMs ?? 5000;
  const timeoutMs = options.timeoutMs ?? 600000;
  if (!Number.isFinite(pollIntervalMs) || pollIntervalMs <= 0 || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
    throw new Error("Polling interval and timeout must be positive milliseconds.");
  }
  const sleep = dependencies.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
  const now = dependencies.now ?? Date.now;
  const report = dependencies.onProgress ?? (() => {});

  async function call(name, args = {}) {
    signal?.throwIfAborted();
    const reply = await client.callTool({ name, arguments: args });
    const structured = reply.structuredContent;
    if (reply.isError || structured?.error) {
      const failure = structured?.error;
      const error = new Error(failure?.message ?? `Tool ${name} could not complete the request.`);
      error.code = failure?.code;
      error.retryable = failure?.retryable ?? false;
      throw error;
    }
    if (!structured || !("result" in structured)) throw new Error(`Tool ${name} returned no structured result.`);
    return structured.result;
  }

  const account = await call("get_account");
  if (!(account.gemBalance > 0)) throw new Error("This account needs a positive Gem balance before creating video.");
  const { capabilities } = await call("list_generation_capabilities");
  const video = capabilities.find((entry) => entry.capability === "video_generation");
  if (video?.availability !== "available") throw new Error("Video generation is currently unavailable.");
  const model = video.models?.find((entry) =>
    (!modelKey || entry.key === modelKey) && entry.capabilities?.inputs?.includes("first-frame")
  );
  const settings = model?.capabilities;
  if (!settings?.durations?.length || !settings.resolutions?.length || !settings.aspectRatios?.length) {
    throw new Error("No matching first-frame model with documented duration, resolution and ratio options was found.");
  }

  const { asset } = imageUrl
    ? await call("import_media_from_url", { url: imageUrl, kind: "image", originalName: "starting-frame.png" })
    : await call("get_media_asset", { assetId });
  if (!asset?.id || asset.kind !== "image" || asset.state !== "ready") {
    throw new Error("The starting frame must be a ready image owned by this account.");
  }
  const request = {
    mode: "image-to-video",
    sourceImage: asset.id,
    model: model.key,
    prompt: options.prompt ?? "A gentle breeze moves the leaves. The camera slowly pushes in. Preserve the subject and composition.",
    duration: String(settings.durations.includes(6) ? 6 : settings.durations[0]),
    ratio: settings.aspectRatios.includes("16:9") ? "16:9" : settings.aspectRatios[0],
    resolution: settings.resolutions.includes("480p") ? "480p" : settings.resolutions[0],
    audio: settings.audioRequired ? "on" : "off",
  };
  const createArguments = { request, idempotencyKey, maxGemCost };
  // Save this checkpoint. After an interrupted Create, reuse these exact
  // arguments; reimporting the URL would produce a different sourceImage ID.
  report({ event: "prepared", sourceAssetId: asset.id, createArguments });
  const accepted = await call("create_video_generation", createArguments);
  let generation = accepted.generation;
  if (!generation?.generationId) throw new Error("Create returned no generation ID.");
  const generationId = generation.generationId;
  report({ event: "accepted", generationId, created: accepted.created, gemCost: generation.gemCost });

  const deadline = now() + timeoutMs;
  const terminal = new Set(["succeeded", "partial", "failed", "cancelled"]);
  while (!terminal.has(generation.status)) {
    signal?.throwIfAborted();
    const remaining = deadline - now();
    if (remaining <= 0) {
      throw new Error(`Polling timed out. The job may still be running; resume get_generation with generationId ${generationId}.`);
    }
    await sleep(Math.min(pollIntervalMs, remaining));
    generation = (await call("get_generation", { generationId })).generation;
    if (!generation || generation.generationId !== generationId) throw new Error("Polling returned an unexpected generation.");
    report({ event: "progress", generationId, status: generation.status });
  }
  const outputs = (generation.outputs ?? []).filter((output) =>
    output.status === "succeeded" && output.asset?.kind === "video" && output.asset.url
  );
  if (!["succeeded", "partial"].includes(generation.status) || !outputs.length) {
    throw new Error(`Generation ${generationId} ended with ${generation.status}: ${generation.error?.message ?? "No ready video output."}`);
  }
  return { generation, outputs };
}

async function main() {
  const env = process.env;
  const accessToken = env.LETSGEN_ACCESS_TOKEN;
  if (!accessToken) throw new Error("Set LETSGEN_ACCESS_TOKEN to an OAuth access token issued for https://mcp.letsgen.app/mcp.");
  if (!env.LETSGEN_MAX_GEMS) throw new Error("Set LETSGEN_MAX_GEMS to your explicitly approved spending limit.");
  const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
  const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
  const client = new Client({ name: "letsgen-image-to-video-example", version: "1.0.0" });
  const transport = new StreamableHTTPClientTransport(new URL("https://mcp.letsgen.app/mcp"), {
    requestInit: { headers: { Authorization: `Bearer ${accessToken}` } },
  });
  try {
    await client.connect(transport);
    const result = await runImageToVideo(client, {
      assetId: env.LETSGEN_ASSET_ID,
      imageUrl: env.LETSGEN_IMAGE_URL,
      maxGemCost: Number(env.LETSGEN_MAX_GEMS),
      idempotencyKey: env.LETSGEN_IDEMPOTENCY_KEY,
      modelKey: env.LETSGEN_VIDEO_MODEL,
    }, { onProgress: (progress) => console.log(JSON.stringify(progress)) });
    console.log(JSON.stringify(result, null, 2));
  } finally {
    await client.close();
  }
}

if (typeof process !== "undefined" && process.argv[1]) {
  const { pathToFileURL } = await import("node:url");
  if (import.meta.url === pathToFileURL(process.argv[1]).href) {
    main().catch((error) => {
      console.error(error.message);
      process.exitCode = 1;
    });
  }
}

The example is exercised against the actual MCP handler and local contract fixtures. It has not been presented as a paid provider run or a live production generation.

08 / Reference

Errors & recovery

Inspect structuredContent.error.code, message and retryable for tool errors. A retryable error is not permission to increase a spending limit or submit a duplicate generation.

CodeNext action
INVALID_REQUESTRefresh capability definitions and correct the input types, model options or owned asset IDs.
NOT_FOUND / OWNERSHIP_DENIEDUse an existing resource belonging to the connected account.
NOT_AVAILABLEChoose an available generator or check your account's access.
NOT_AFFORDABLECheck your Gem balance before creating another generation.
PRICE_CHANGEDReview the current request and obtain a new spending limit if needed. Do not silently raise maxGemCost.
IDEMPOTENCY_CONFLICTReuse the original arguments for that key. A genuinely new generation needs a new key and spending approval.
IMPORT_BLOCKEDUse a direct public HTTPS media file of the selected kind and within the import limits.
SECURITY_BLOCKED / SAFETY_BLOCKEDReview connection access or change the creative request as appropriate.
PROVIDER_FAILED / TEMPORARILY_UNAVAILABLEInspect the generation state and retryable flag. Do not create a duplicate job just because polling failed.

For OAuth or HTTP failures, let the client follow the server challenge and check the connection, resource and granted scopes. A 403 by itself does not identify expired credentials. Reconnect only when needed; never silently broaden access.

For pending work, use list_generations or the saved generation ID to find the original job. There is no public MCP cancellation or retry-generation tool.

Return to Lets Gen MCP →