Create from your AI assistant.

Connect your assistant#

For guided setup, choose your assistant on the MCP connection page.

V4V MCP lets an AI assistant discover generation models, work with reference media, create images, video, audio and chat responses, and retrieve results. It uses the same account, credits and generation history as the V4V API.

Server URL: https://v4v.ai/api/mcp

Transport: Streamable HTTP

Authentication: OAuth 2.1 sign-in on enabled deployments, or an API key in clients that support custom request headers. Both use your existing V4V account and credits.

Use your deployment's domain in place of v4v.ai when testing another environment. The server is already hosted; you do not need to run a local process.

Sign in with OAuth

Choose this option in ChatGPT, Claude, or a supported editor or CLI. You do not need to create an API key. Add the remote server URL, select OAuth / Sign in, and complete the V4V permission screen. See OAuth authorization and the client-specific steps below.

Connect with an API key

1. Open your V4V profile and create a key under API Keys.
2. Save the API secret in your MCP client's secure settings.
3. Add the server with x-api-key: YOUR_V4V_API_KEY or Authorization: Bearer YOUR_V4V_API_KEY.
4. Connect and start with get_balance or list_models.

Send one authentication header. If both are sent, they must contain the same key; conflicting or malformed credentials return HTTP 401. The x-api-key value is the key itself, without a Bearer prefix. Both API-key header formats use the same permissions, credits, rate limits and key revocation.

API-key clients continue to use the same headers and permissions. OAuth clients sign in to their existing V4V account through the browser. Never paste a key or token into an assistant conversation or commit it to a repository.

OAuth 2.1 authorization#

1. Add https://v4v.ai/api/mcp as a remote Streamable HTTP server in your assistant.
2. Choose OAuth / Sign in. If asked for an OAuth client, select Register automatically (dynamic client registration, or DCR). Leave Client ID and Client Secret empty.
3. Your assistant opens V4V in your browser. Sign in to the V4V account whose credits and library you want to use.
4. Review the assistant and all three required permissions: view your account and media; upload, estimate costs, edit and share; generate media and transcribe using credits. All three are selected and locked. Choose Accept all permissions, or Cancel to decline.
5. Return to your assistant, finish connecting if prompted, and ask it to check your balance. Tool permissions and confirmations inside the assistant are managed separately by that client.

The assistant discovers the OAuth endpoints from the server and uses PKCE to complete sign-in. Do not create an API key or paste a bearer token for this flow. The OAuth example at the top of this page contains only the HTTP transport and server URL; each client has its own configuration format.

Connecting does not spend credits. Generations use your existing V4V balance. Access tokens last at most one hour and refresh automatically when the client supports it. The connection expires after 30 days; reconnect then or after revoking access. Manage and disconnect sessions in V4V profile → Assistant connections. Already submitted jobs continue running after disconnection.

If OAuth is unavailable on your deployment, ask its operator to enable assistant connections, or use an API key in a compatible client.

ChatGPT (OAuth)#

OAuth must first be enabled on the V4V deployment. Account and workspace permissions in ChatGPT determine whether a custom MCP connection is available.

1. Open ChatGPT Plugins → Personal, choose Add (or +), then Add custom MCP server (the label may differ by account).
2. Enter V4V and server URL https://v4v.ai/api/mcp.
3. Choose OAuth and dynamic client registration (DCR). Leave Client ID and Client Secret empty; V4V registers a public PKCE client automatically. This version supports DCR, not CIMD.
4. Connect and sign in using your existing V4V login.
5. On V4V's permission screen, review the account and callback host. All three permissions are required: reading the account, editing/uploading and generating with credits. The three checkboxes are selected and locked. Choose Accept all permissions to connect, or Cancel to decline; partial consent is not supported.
6. Return to ChatGPT and install the plugin if asked. In Personal plugins, open V4V's three-dot menu and choose Manage.
7. Open the Permission row. For approval-free tool calls, choose Allow all tools. Generations still use your V4V credits, so ask for an estimate before starting.
8. Start a new conversation, choose + → Plugins → V4V (or mention it with @), and ask Check my V4V balance.

The ChatGPT screenshot guide walks through all eight screens. Its connection-details step has copy buttons for the plugin name, description and current deployment's server URL, plus an optional V4V icon download.

Example:

Create three vertical 9:16 product video concepts from this product link. Show the concepts and estimated credits first. Wait for my approval before starting generation.

The assistant uses the existing discovery, estimate_generation, and generate_studio_variants tools. Estimates do not render or reserve credits, but may import media for validation and therefore require the editing permission. Paid tools enforce the generation permission on the server. The permission is account access, not approval of an individual creative brief: still review the requested concepts and budget before authorizing a render. Batch max_credits and idempotency controls remain in effect.

Access tokens last at most one hour. Refresh tokens rotate on use, and the connection expires after 30 days. Reconnect when it expires or when additional permissions are needed. In V4V profile → Assistant connections, review usage, disconnect the assistant, or reveal its webhook signing secret for your receiver. Do not paste the signing secret into chat.

Disconnecting blocks new tool requests, token refresh and unused upload links. Already submitted jobs continue under the existing queue and credit rules; disconnecting does not cancel or refund them. Previously issued signed media links retain their normal expiry.

File uploads from ChatGPT's execution environment depend on that environment's network and attachment access. The scoped browser upload link remains available as a fallback. MCP connectivity alone does not guarantee automatic attachment transfer.

Custom connection testing and public plugin publication are separate steps. See OpenAI's MCP connection guide, OAuth requirements, and public review requirements.

Claude Web#

OAuth connection

Open Add to Claude. The form opens with the V4V name and production server URL prefilled. For dev or another deployment, use the connection page, which fills that deployment's URL. If signing in to Claude clears the form, reopen the link after signing in.

Follow the six-step screenshot guide alongside Claude:

1. Review the prefilled name and URL, then choose Continue.
2. Claude checks the server automatically. Keep the detected Sign in now and Register automatically settings and choose Add; no other settings need changing. Leave Client ID and Client Secret empty, with no API key or request headers.
3. On the connector page, choose Connect and sign in to V4V.
4. Review your account and all three required permissions, then choose Accept all permissions. Connecting does not spend credits.
5. Under Tool permissions → Read-only tools, open Custom next to the group name and choose Always allow.
6. Scroll to Write/delete tools and choose Custom → Always allow for that group too. Enable V4V in a conversation and ask Check my V4V balance. Generations use your V4V credits; ask for an estimate first.

Claude's tool permissions are separate from the V4V account authorization. The group menus let you allow the tools without changing each one individually. You can revise these choices in Claude's connector settings.

Claude's hosted callbacks on claude.ai and claude.com are supported without extra environment configuration. Use Register automatically; Claude's published client identity (CIMD) is not implemented in this release. Existing API-key connections continue to work as described below.

If transport settings are shown, use Streamable HTTP. Adding a connector and authorizing its account access are separate steps when Claude presents them that way.

API-key alternative: create your V4V API key

Open your V4V profile, go to API Keys, and create a key. Keep it ready for the connector header below.

2. Add the connector

1. Open Add to Claude, or open Customize → Connectors → Add → Custom web connector.
2. Set Name to V4V.
3. Set MCP server URL to https://v4v.ai/api/mcp.
4. Under Authentication, select No sign-in.
5. Click Add header and enter:

6. Click Add / Connect and wait for the connection to complete.

Use the key alone in x-api-key, without a Bearer prefix. No sign-in skips OAuth; the header still authenticates every request to V4V. Leave OAuth Client ID and Client Secret empty.

3. Allow the tools

1. Open Claude's Connectors manager.
2. Select the new V4V connector.
3. Open Tool permissions and allow all V4V tools.
4. Confirm that create_upload_link, get_upload, get_model and generate_lab are available and enabled.

After V4V adds or updates tools, refresh the connector's tools or reconnect it before starting a new conversation.

4. Allow automatic file uploads

1. Open Settings → Capabilities.
2. Enable Code execution and file creation and Allow network egress if they are off.
3. In Domain allowlist, add these entries:

v4v.ai
*.v4v.ai
*.v4vcdn.space

Keep both the root domain and the wildcard entry so the app domain and its subdomains are covered. Enter domain names only, without https:// or /api/mcp, and save the changes. If your workspace manages this setting centrally, ask its administrator to update the allowlist.

This allows Claude's execution environment to send the original attachment directly to V4V using the short-lived upload permission issued by MCP. Without this setting, the connector may work while file uploads fail with host_not_allowed.

Testing on dev: use https://h4000.kitpes.com/api/mcp as the connector URL and add h4000.kitpes.com separately to the Domain allowlist. The V4V domain entries do not cover the dev hostname.

5. Start a new conversation

Enable the V4V connector in a new chat, attach your image, and ask:

Upscale this image 4× with V4V. Upload the original file automatically, then use its file ID with the Topaz model.

Claude should obtain an upload permission through MCP, transfer the file from its execution environment without copying base64 into chat, and submit the generation. You do not need to upload the file again in a separate browser page when network access is allowed.

For Claude's general connector and network controls, see connector management and code execution and network access.

VS Code#

OAuth sign-in

Use Install in VS Code on the connection page, or add this to .vscode/mcp.json:

{
  "servers": {
    "v4v": {
      "type": "http",
      "url": "https://v4v.ai/api/mcp"
    }
  }
}

Start the server, review the trust prompt and complete V4V sign-in when VS Code opens your browser. Enable the tools you want to use in agent chat.

API-key alternative

For editor chat, add the following to .vscode/mcp.json. VS Code prompts for the key and masks the input. Keep the placeholder in the file.

{
  "inputs": [
    {
      "id": "v4v-api-key",
      "type": "promptString",
      "description": "V4V API key",
      "password": true
    }
  ],
  "servers": {
    "v4v": {
      "type": "http",
      "url": "https://v4v.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:v4v-api-key}"
      }
    }
  }
}

Start the server from the MCP configuration and enable its tools in your chat session. Review the generation tool call before allowing it to spend credits.

For other VS Code agent environments, follow the current MCP configuration reference for the configuration location supported by that environment.

Claude Code#

OAuth sign-in

Register the remote server without an authentication header:

claude mcp add --transport http v4v https://v4v.ai/api/mcp

Start Claude Code, run /mcp, choose V4V and authenticate. Complete the V4V permission screen in your browser, then return to the CLI.

API-key alternative

Set V4V_API_KEY securely in your shell environment, then register the remote server:

claude mcp add --transport http \
  --header "x-api-key: $V4V_API_KEY" \
  v4v https://v4v.ai/api/mcp

Use /mcp inside Claude Code to inspect the connection. The registration stores the configured header in your local client configuration; protect that file and keep it out of source control. See Claude Code's MCP guide for configuration scope and key management.

Cursor#

On the connection page, choose V4V sign-in or API key and click Install in Cursor. Review the installation in Cursor before accepting. OAuth opens a browser sign-in; API-key setup installs a placeholder that you replace locally in .cursor/mcp.json. No real key is embedded in the install URL. Current desktop versions use an HTTP loopback callback; cloud clients use the exact approved https://www.cursor.com/agents/mcp/oauth/callback URI.

Codex CLI#

For OAuth, add the server and sign in:

codex mcp add v4v --url https://v4v.ai/api/mcp
codex mcp login v4v

For an API key, securely set V4V_API_KEY in your environment, then run:

codex mcp add v4v --url https://v4v.ai/api/mcp --bearer-token-env-var V4V_API_KEY

Gemini CLI#

Add the remote server with gemini mcp add --transport http v4v https://v4v.ai/api/mcp. Run /mcp auth v4v inside Gemini CLI for OAuth. For API-key setup, set V4V_API_KEY securely and add the server with gemini mcp add --transport http --header "x-api-key: $V4V_API_KEY" v4v https://v4v.ai/api/mcp. The CLI saves the configured header; keep its settings private.

OpenCode#

Add a remote server under mcp.v4v in opencode.json with type: "remote", url: "https://v4v.ai/api/mcp" and enabled: true. Run opencode mcp auth v4v for OAuth. The connection page provides the full JSON and an environment-variable API-key alternative.

Other MCP clients#

Choose a remote / Streamable HTTP server and supply:

Configuration formats vary by client. Configure the header in the client's secret settings, not in a chat message. Legacy SSE-only clients are not supported. Supported native OAuth clients use HTTP callbacks on localhost or 127.0.0.1 with an explicit local port. Registration and authorization bind the complete callback URL exactly. Hosted callbacks for Claude, ChatGPT, Cursor and VS Code are approved; other hosted clients need exact URLs in MCP_OAUTH_REDIRECT_URIS.

Start with a brief#

You can start with a request like:

Find a model for an eight-second vertical video of my ceramic mug. Use this product image: https://example.com/mug.jpg. Show me a concept and the required inputs before generating.

The assistant should discover a suitable model, inspect its schema, check the balance, and prepare the inputs. Once you request the generation, it submits a task and checks for the finished result.

For a complete product-video workflow, use generate_studio. For a specific image, video, audio, translation or chat model, use generate_lab.

The video_brief prompt helps turn a goal, audience and format into a shot plan. The v4v://guide resource explains the generation workflow to your assistant.

Available tools#

Studio discovery reads the selected workflow and active styles from this deployment; it does not hardcode seven style names or assume every workflow has a ten-second limit. get_model with model: "studio" is an alias for describe_studio. Essential instructions are also in tool descriptions for clients that cannot read v4v://guide.

Model schemas come from the same catalogue used by V4V LAB. Ask for get_model before choosing parameters; required references, durations and formats vary by model.

Reuse library content and preview cost#

Call list_products or list_avatars (optional offset and limit, maximum 100). Avatars default to source: "all"; owned and public filters are available. The returned next_offset is null on the last page. Public avatar IDs include public:; keep this prefix. Each record includes photo_count; Studio uses the avatar's primary photo. Only your own private library records are returned.

Use input.product_id and input.avatar_id in generate_studio or estimate_generation. parameters.avatar also accepts the returned avatar ID and continues to support a file ID or public image URL. Choose either input.avatar_id or parameters.avatar. Library photos are resolved directly without downloading and uploading them again. Explicit product name, description or image inputs override the saved product's defaults. Active style IDs/names use their saved creative instructions; unknown or inactive style IDs/names return INVALID_PARAMETER with allowed_values. Put free-form creative directions in input.prompt and choose an active preset (or omit style for the discovered default).

{
  "source": "studio",
  "input": {
    "product_id": "0123456789abcdef01234567",
    "avatar_id": "public:0123456789abcdef01234568",
    "prompt": "A short product review"
  },
  "parameters": {
    "duration": 10,
    "style": "Product Review"
  }
}

Send that to estimate_generation. It returns credits_estimated, reserves zero credits and creates no task or render. Studio quotes skip provider character registration, including when an avatar is selected. Public media URLs may be imported for validation. Quotes can change with inputs/pricing; chat quotes describe an initial reservation, not final token costs or a spending cap. To render, remove source and submit the same inputs to generate_studio with a new idempotency_key.

Variants, project names and examples#

generate_studio_variants accepts name, shared input/parameters, a required max_credits, idempotency_key, and variants containing two or three objects with optional input/parameter overrides. For example: variants: [{parameters: {style: "UGC"}}, {parameters: {style: "Product Review"}}]. Each variant is a separate paid attempt. This is a wrapper over the existing Studio batch queue: it returns batch_id, uses get_studio_batch for results and the same pause/budget/rework controls. It never bypasses capacity limits.

Use rename_project with the project_id returned by list_projects, generation or get_task, and project_name (trimmed, 1–200 characters). Renaming also updates the task title and LAB history, including when a project is still waiting to be created. It does not change the original idempotency request hash.

Only examples administrators discover promote_to_example. It takes an owned project_id with a saved result, required active, and surfaces: ["dashboard", "studio", "landing"] (choose any subset). studio maps to the existing ProVid/Studio visibility flag. active: false hides the example everywhere regardless of surface selection. The result includes visible_on so the effective visibility is clear. Publishing requires a user request; this tool does not spend generation credits.

Organize existing projects#

Use list_projects to find existing projects without generating. It includes Studio, workflows, LAB history and queued API projects. Optional filters: source: "all" | "studio" | "workflow" | "lab", q for literal title search, and folder_id for an owned folder or "unfiled". Omit the folder filter to see all projects. Both list_projects and list_project_folders accept offset (default 0) and limit (1–100, default 50); follow next_offset until it is null.

For example, to organize approved campaign results:

1. Call list_projects with {"q":"approved"} and select the intended projects.
2. Call list_project_folders; reuse the intended folder or call create_project_folder with {"name":"Summer campaign"}.
3. Call move_project for each selected project_id with the returned folder_id.
4. Call list_projects with that folder_id to verify the folder's contents.

Use move_project with folder_id: null to remove a project from its folder. rename_project_folder accepts folder_id and name. Folder names must contain 1–80 characters after trimming and be unique in your account; a duplicate returns FOLDER_NAME_CONFLICT. After an uncertain create response, list folders before retrying. Moves and renames are safe to repeat and do not spend credits, generate media, or change results. Queued projects retain their names and folders when the worker creates them. These operations cannot access another account's projects or folders.

Media and generation#

Reference media can be a public URL or an owned V4V file ID. A field named image_url accepts a file ID too; use the model schema to choose the exact input field.

Automatic uploads from attached and local files

The assistant can upload the original file itself when its execution environment can reach this V4V deployment. You do not need to copy an API key into chat or select the same file again.

1. Call create_upload_link. Despite its name, the tool also returns upload_request: a POST URL, a scoped x-upload-token header and the multipart field name file.
2. From the assistant's execution tool, send the actual local file bytes to that URL using multipart/form-data. Let the HTTP client set the boundary and disable redirects. Do not convert the image or print base64 into the conversation.
3. Read the response's file_id and confirm with get_upload using upload_id.
4. Discover the model's input schema, pass that ID into its media field (such as Topaz image_url), and submit the requested generation.
5. For multiple references, repeat with a separate upload slot for each required file.

The upload token expires after 15 minutes, accepts one file up to 20 MiB subject to the server limit, and cannot read your library or spend generation credits. The actual bytes travel over HTTP; MCP supplies the scoped authorization and controls the generation.

For an execution environment with the tool result available as slot, the binary transfer is:

import requests

upload = slot["upload_request"]
with open(local_file_path, "rb") as source:
    response = requests.post(
        upload["url"],
        headers=upload["headers"],
        files={upload["file_field"]: (filename, source, content_type)},
        allow_redirects=False,
        timeout=120,
    )
if response.status_code != 200:
    raise RuntimeError(f"Upload failed: HTTP {response.status_code}")
file_id = response.json()["file_id"]

Allowing the upload hostname in Claude

MCP connectivity and sandbox network access are separate. host_not_allowed means the sandbox cannot send the binary upload even though MCP calls work.

Follow Claude Web → Allow automatic file uploads above: open Settings → Capabilities → Domain allowlist, add v4v.ai, *.v4v.ai, and *.v4vcdn.space, and enable network egress. For dev, add h4000.kitpes.com separately. Workspace-managed restrictions may require an administrator to make the change.

The assistant must stop after the first denied request and explain the required setting, not retry for minutes or convert the file into model text. Start a fresh conversation after updating permissions and refresh the connector's tools after a server update.

Optional browser fallback

If you choose manual upload, open upload_url, select the original file, and tell the assistant when it is ready. It retrieves the file ID with get_upload. This is a fallback, not a required step when automatic HTTP upload works.

upload_media remains for programmatic byte forwarding or tiny payloads up to 8 KiB encoded. Its 5 MiB decoded server limit is not a practical language-model text budget. Do not resize/recompress a source merely to transfer it, print large base64 strings, or loop over encoded chunks.

REST upload for larger files

If the assistant's execution environment has outbound network access and a securely configured API key, it can upload through POST /api/v1/files using the multipart field file. The MCP connector's key is not automatically available to shell tools.

# V4V_BASE_URL is this deployment's origin, e.g. https://h4000.kitpes.com
curl "$V4V_BASE_URL/api/v1/files" \
  -H "Authorization: Bearer $V4V_API_KEY" \
  -F "file=@/path/to/photo.png"

The response's id is the file ID to use in generation inputs. Let curl set the multipart boundary. Keep credentials in secure client configuration, not in the conversation.

Public URLs

Use import_media to save an accessible media URL for reuse, or supply the URL directly to the model. Do not pass a local path or a sandbox URL as a public URL.

Example arguments for generate_lab (replace the sample ID with the ID returned by your upload):

{
  "model": "image-upscale-topaz",
  "project_name": "Product detail — enlarged",
  "input": {
    "image_url": "0123456789abcdef01234567"
  },
  "parameters": {
    "upscale_factor": "2"
  },
  "idempotency_key": "product-detail-upscale-001"
}

Example arguments for generate_studio:

{
  "project_name": "Ceramic mug — launch video",
  "input": {
    "product_name": "Ceramic mug",
    "product_description": "A handmade mug with a matte glaze",
    "product_images": [
      "https://example.com/mug.jpg"
    ],
    "prompt": "A calm product reveal in soft morning light"
  },
  "parameters": {
    "duration": 8,
    "aspect_ratio": "9:16"
  },
  "idempotency_key": "mug-launch-video-001"
}

Use a new idempotency_key for each intentional generation. Reuse the same key and arguments when retrying a request after a network interruption. Reusing a key with changed inputs returns a conflict.

Retrieve the result#

Generation tools return task_id and project_id immediately. If the account concurrency limit is full, the same task waits with credits_reserved: 0, credits_estimated, and queue details containing the configured limit, a five-second check interval, and estimated_start_at: null. Completion times cannot be predicted. Do not submit another generation to bypass waiting. The worker reserves credits when a slot opens; if the balance is insufficient then, the task fails at the admission stage and sends its configured webhook. They do not hold the conversation open until rendering finishes.

{
  "task_id": "task_6aa962444bd1dd7ab65bc6b6"
}

Pass that ID to get_task. Wait at least five seconds between checks. A task can be queued, processing, completed, failed, or cancelled.

When the status is completed, results contains inline text for chat or signed download URLs for media. The assistant can share these URLs with you without requiring browser cookies. Use get_task or refresh_task_results if a link expires. Media results include stable asset_id/file_id; pass file_id directly into future generation media fields instead of copying an expiring URL. The next-day reuse contract is the stable ID plus a renewable link while the file exists and access remains allowed; the URL itself can expire. Links stay signed; never remove the signature or derive an unsigned CDN path. Stop polling on any terminal status. Checking a task never starts a second generation. Failed tasks report error.stage, brief_completed, retryable, and suggested retry_after_seconds where known, alongside the actual credits_used. A completed brief can retain its charge even when video generation fails. retryable: true describes a potentially transient error; it does not authorize another paid attempt. If the task returns GENERATION_SERVICE_ERROR, the model service reported an internal failure. Do not assume the source resolution or scale factor caused it, or automatically switch models or create new paid attempts. Explain the failure and wait for a requested retry.

LAB generations also appear in LAB → Old runs and Projects. Your API-key usage appears in your profile.

Completion webhooks#

generate_lab and generate_studio accept callback_url using the existing REST webhook delivery and signature verification. V4V posts task.completed or task.failed with stable event_id, task data, credits and results. Verify X-V4V-Timestamp and X-V4V-Signature using the webhook signing secret shown when the API key was created, and deduplicate by event_id. Do not paste secrets into chat. Delivery retries do not create new generations. Callback URLs use the same external-network validation as REST. Bulk and variant submissions also accept callback_url for signed batch events; see the monitoring workflow below. See REST webhook verification.

Credits and access#

Generation uses your normal V4V credits. For ordinary LAB/Studio tasks, estimated cost is reserved when capacity is available; excess tasks wait without a reservation. Unused credit follows the same release rules as the REST API. Looking up models, balances, tasks and existing files does not spend generation credits.

Each tool is scoped to the owner of the configured key. Another account's files and tasks cannot be accessed. Revoke a key in your profile to disable its MCP connection. Tool annotations identify calls that create work and spend credits, so your client can offer its normal tool-approval controls.

Troubleshooting#

The service uses the official MCP TypeScript SDK and a stateless JSON response mode over Streamable HTTP. Bounded wait tools keep the individual request open until an update or timeout; they do not establish a permanent notification channel. The client negotiates the protocol version when it connects.

GPT Image 2.5 image variants

Model discovery includes Flare and Sunburst text/image variants with Sunburst defaults for image.text_to_image and ai.image_edit. They support background, 1K/2K/4K pricing (6/10/16 credits), prompts up to 20,000 characters, and up to 16 edit images. See GPT Image 2.5 settings and API examples for variant IDs and aspect-ratio restrictions.

GPT-6 Astra chat#

Use list_models with {"type":"chat"}, then get_model with {"model":"chat.gpt_6_astra"} to inspect current inputs, token rates and rounding. Submit using generate_lab:

{
  "model": "chat.gpt_6_astra",
  "input": {
    "prompt": "Explain this idea in three sentences."
  },
  "parameters": {
    "reasoningEffort": "low",
    "webSearch": false,
    "stream": false
  },
  "idempotency_key": "astra-question-001"
}

Optional input.imageUrls accepts up to 12 public URLs or owned file IDs. Text-only requests use string input upstream; images use Kie's multimodal message array. Optional input.functionTools accepts a JSON string of function definitions; web search must be off when functions are present. Kie receives tool_choice: "auto", and completed task results include function_calls for the caller to handle. The model node does not execute functions. Poll get_task using the returned task ID. Completed results entries have type: "text", text, usage, credits and incomplete instead of a download URL.

Chat initially reserves 1 credit. Final cost uses actual input, cache and output tokens, rounded up to a whole credit with a minimum of 1. Any amount above the reservation is deducted after the response; the initial reservation is not a spending cap. Token rates are published by get_model. Reuse the same idempotency key and arguments for network retries; do not submit another paid generation automatically after a failure.

Bulk Studio product videos#

Use generate_studio_bulk when you want videos for a list of products. It accepts 1–300 items and returns a batch_id immediately. It shares the account's normal credit balance and the global KIE generation queue with REST and the web application.

{
  "name": "Autumn product videos",
  "input": {
    "prompt": "Show three benefits in a calm product reveal"
  },
  "parameters": {
    "duration": 8,
    "aspect_ratio": "9:16"
  },
  "max_credits": 500,
  "test_count": 5,
  "items": [
    {
      "sku": "MUG-01",
      "product_id": "0123456789abcdef01234567"
    },
    {
      "sku": "BAG-02",
      "product_url": "https://shop.example/products/bag?variant=blue"
    },
    {
      "sku": "LAMP-03",
      "input": {
        "product_name": "Desk lamp",
        "product_images": [
          "https://shop.example/lamp.jpg"
        ]
      },
      "parameters": {
        "style": "TV Spot"
      }
    }
  ],
  "idempotency_key": "autumn-products-001"
}

Item input and parameters override the shared settings; Studio defaults fill the rest. Supply owned product IDs, public product page URLs, or prepared product details and media. Use the settings supported by the deployment's current Studio model. Omit test_count to process the whole list. With test_count: 5, the first five items (or all items if fewer than five) run before the batch pauses for review.

DIRECTOR_REQUEST_FAILED identifies rejection of the AI Director text request; REFERENCE_MEDIA_UNAVAILABLE identifies a problem reading its reference files. Explain the failed stage and report the task ID; never assume these mean a KIE video request failed or automatically create another paid attempt.

Public eBay item URLs support a protected browser import fallback. If a store still rejects an import, send an owned product_id or prepared product details/images. IMPORT_FAILED occurs before paid admission and includes the known import reason; PREPARATION_FAILED identifies a later preparation failure. A failed attempt stays terminal. When the user requests a retry, call control_studio_batch with action: "retry_failed" and a new idempotency_key; optionally provide zero-based item_indexes. For corrected inputs or a deliberate remake, use action: "rework" with items: [{task_id: "task_…", input: {prompt: "New direction"}}] (or use index: 1 instead of task_id). Use action: "restart" only when the user requests all items again, including successes. These three actions require a new key for each intentional operation; replay the same key and arguments on network errors. resume does not retry failed attempts.

To remake only the results you dislike, select their current items[].task_id and call control_studio_batch with action: "rework", those IDs in items, and a new idempotency_key. Omit input changes to rerun the same brief. Selected current results clear immediately and the same batch resumes processing; other completed items stay unchanged. items[].results always describes the latest intended version, while attempts preserves the older output. A stale replaced task ID returns BATCH_ITEM_VERSION_CHANGED; read the batch again before a new intentional rework.

Monitor a batch in Claude's browser connector

A webhook sends an HTTP request to a real receiver. It does not give this MCP connection a way to restart an idle Claude browser conversation. Never invent a callback URL or promise a future chat message after the conversation has ended.

During the user's requested batch workflow, Claude should monitor automatically:

1. Keep the batch_id and state_token from generate_studio_bulk, generate_studio_variants, or get_studio_batch.
2. Call wait_studio_batch with batch_id, after_state set to that token, and wait_seconds: 25 for browser connectors. Optional pagination uses offset and limit (default 50, maximum 100).
3. The server returns on a meaningful batch change, completion, pause, cancellation, or the bounded timeout. Worker heartbeats and expiring result signatures do not change the token. The response contains the updated batch page, changed, timed_out, stop_reason, and next_action.
4. While status is running, continue waiting with the returned token without asking the user to say “check again”. Report useful milestones, not every unchanged timeout. A timeout does not fail or cancel generation. Do not submit a replacement batch.
5. On completed, report results and failures. On paused, explain waiting_reason and wait for the user's decision. Never automatically resume, increase a budget, or retry paid attempts. cancelled also ends this monitoring loop.

This uses server-side long polling inside an active tool workflow. If Claude ends its turn, the user closes the conversation, or the client enforces a runtime limit, the batch still runs but this connection cannot guarantee a new chat message. Cancelling/disconnecting a wait only stops observation, not the batch. Checking or waiting spends no generation credits.

wait_seconds accepts 1–240 seconds. Claude Code supports automatically backgrounding long MCP calls in recent versions; for a 240-second wait, configure that server's timeout to at least 300000 milliseconds and allow the request through proxy timeouts. Browser connectors should use the 25-second default. See Claude Code long tool calls. This behavior is client-specific and is not a browser wakeup guarantee.

Batch webhooks for external receivers

Pass callback_url when creating a bulk batch or variants. The existing API-key webhook signing secret and X-V4V-Timestamp / X-V4V-Signature verification apply. The callback destination is fixed by the idempotent creation request; replay the same URL and arguments after network errors.

The worker records meaningful snapshots and delivers batch.updated, batch.completed, batch.paused, and batch.cancelled. Events include stable event_id, batch_id, batch_revision, observed_at, state_token, status, counts and credit totals. result_lookup points to get_studio_batch for paginated files and task details; webhook payloads do not embed expiring result URLs. Intermediate transitions can be coalesced between worker ticks.

Delivery uses a durable outbox with leases and bounded retries. Repeated delivery has the same event ID and payload; signatures are refreshed per attempt. Receivers must deduplicate and tolerate out-of-order delivery, then fetch current batch state when needed. Permanent HTTP errors abandon delivery; transient failures back off. A slow webhook receiver does not block the generation/admission worker. Pauses, cancellations with active work, and later requested restarts/reworks continue to produce updates. Delivery never starts another paid attempt.

For occasional manual status reads, call get_studio_batch at least five seconds apart; for active agent monitoring prefer wait_studio_batch. Individual attempts use the ordinary get_task tool for signed download links. These tools continue processing on the server without the conversation or a browser tab remaining open.

Bulk queues reserve only the next admitted item's estimate. max_credits bounds spent credits plus active reservations. Insufficient balance or budget pauses new starts; after the user requests it, call control_studio_batch with action: "resume", optionally increasing max_credits. Pause/cancel lets active attempts finish. Cancelled batches cannot resume, but can explicitly restart or rework terminal items after admitted work finishes. Selected items must be terminal (BATCH_ITEMS_ACTIVE); active or uncertain provider requests block retries (GENERATION_UNRESOLVED). NO_FAILED_ITEMS means no latest failures remain. History, results and cumulative spending survive all operations; counts and item status use only the latest intended versions. New versions share the same queues and Credit Log attribution. Optional operation-wide input/parameters changes merge over the previous request, and per-item rework overrides win. A preserved sample gate still requires explicit resume; restart removes it. See the REST contract for request/history limits and full examples. Reuse the same idempotency_key and arguments after a network error; never create another batch to bypass queue waiting.

KIE requests share at most 10 active slots across accounts and application processes. Ordinary generation has priority; bulk uses spare capacity under administrator-defined global and per-user limits. A lost provider response keeps its slot occupied for reconciliation and never triggers an automatic duplicate paid request. API and MCP credit events are labelled separately in the administrator's Credit Logs.

This release provides generation and individual downloads through API/MCP. The broader plan's Studio bulk screens, CSV upload, result approval and ZIP export remain future work. Refresh your MCP connector's tool list after deployment to discover the new batch tools. See the REST bulk contract for fields, budget semantics and errors.

Video Editor#

The editor at /video-editor lets you and your assistant work on the same saved, multi-layer timeline. It supports video, images/logos, source audio, independent music/voice layers, text, timed captions, trimming, splitting, speed, volume, fades and take-review notes. The browser provides interactive preview and local MP4/WebM export. Open Video Editor to edit interactively; the tools and limits are described below.

Start with get_editor_guide (also available as resource v4v://video-editor). Refresh the connector's tool list after deployment.

Editor project IDs are separate from Studio/LAB generation project IDs. Use list_editor_projects, not list_projects, to discover them. Generation remains available through the existing model discovery, estimate and generate_lab tools. Completed media's file_id can be used directly as timeline assetId. Speech-to-text is also discoverable as type: "subtitle"; its completed API task results contain timed cues in seconds and SRT. The dedicated editor transcription tools simplify using an existing Library source.

A typical agent request:

Build a 20-second vertical film from my Library clips. Review representative frames and replace the distorted take with a new generation after showing its cost. Trim the shots, add my logo, quiet background music, a voiceover and timed captions. Save the finished video to Library and give me a download link.

The assistant should:

1. Read the guide, find the project and source media, and inspect durations and playback.
2. Create or edit the timeline using its current revision. Add a logo as an image on an upper visual layer and voice/music on audio layers. Original media is unchanged.
3. Use preview_editor_project to inspect selected frame times. Set clip review: "keep" or "replace" and record the reason in note. Frames do not establish motion or sound quality; inspect source playback too.
4. Discover/estimate requested models, generate replacements with unique idempotency keys, and wait for their completed file IDs. Replace the selected clip's source and clamp its trim/duration to the new source.
5. Quote/transcribe the original voice source, poll at least five seconds apart, then add cues with sourceClipId to account for trimming and speed. Review transcription text. Supplying existing timed cues costs no credits.
6. Submit the current revision with export_editor_project; poll get_editor_export at least five seconds apart while queued/rendering. A disconnected MCP request does not cancel the job. Only completed with an asset ID and download URL means success; inspect failures before explicitly retrying with retry_failed: true. Create a share link only if requested.

Example targeted edit after get_editor_project:

{
  "project_id": "PROJECT_ID_FROM_CREATE",
  "revision": 3,
  "operations": [
    {
      "type": "update_clip",
      "clipId": "shot-1",
      "changes": {
        "trimStart": 1.5,
        "duration": 3,
        "volume": 0.25,
        "review": "keep"
      }
    },
    {
      "type": "split_clip",
      "clipId": "shot-2",
      "time": 7,
      "newClipId": "shot-2b"
    },
    {
      "type": "add_captions",
      "sourceClipId": "voice-1",
      "cues": [
        {
          "start": 0.2,
          "end": 2.1,
          "text": "A new perspective."
        }
      ]
    }
  ]
}

start/duration use timeline seconds, trimStart uses source seconds, and the split time is an absolute timeline time. Read actual media duration before trimming. add_clip accepts a clip with unique id, trackId, kind, assetId, start, and duration; other fields have defaults. Text uses kind: "text" and text instead of an asset. Track kinds are visual, audio, or text. add_track, update_track, remove_track and reorder_tracks manage layers. Tracks render in array order, last on top. Overlap visual layers and use fades for dissolves.

The server rejects inaccessible media, mismatched media types, invalid trims and stale revisions. On a revision conflict, read the new version and reapply intended changes. Do not overwrite the other editor's work. Open clean browser editors pick up agent changes automatically; locally modified drafts retain their changes and show conflicts.

Agent frame inspection/export requires Playwright Chromium on the deployment. Agent exports support up to two minutes and 300 MB source media, and return a saved WebM; a repeated same-revision export reuses its existing asset. Browser export supports ten-minute timelines and offers MP4 when the device has H.264/AAC encoders. If rendering fails, report the error and editor link; do not claim a successful export. Timeline editing/rendering spends no model credits; generation/transcription does. Sharing creates a link visible to anyone with the link.

Gemini text-to-voice#

Use list_models with type="audio", then get_model for ai.gemini_3_8_flash_tts or ai.gemini_3_8_flash_lite_tts. Both generate single-speaker WAV audio from up to 10,000 spoken characters:

{
  "model": "ai.gemini_3_8_flash_tts",
  "input": {
    "text": "Welcome! <short pause> Let’s get started."
  },
  "parameters": {
    "voice": "Kore",
    "style": "Warm and friendly"
  },
  "idempotency_key": "unique-intentional-generation-id"
}

Read get_model.voices for each preset’s exact id, gender, description and free preview_url. Send the selected ID as parameters.voice; omit metadata and preview URLs from generation arguments. Check the balance and call estimate_generation with source="lab" first, then call generate_lab. Read get_task for owned audio file IDs and signed download links. Delivery instructions belong in style; they are not spoken. Flash focuses on expressive narration, Flash-Lite on efficient generation. Provider selection is managed in admin settings, not through an MCP parameter. ElevenLabs text-to-voice is temporarily disabled.