Create from your AI assistant.

Connect your assistant#

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: use either Authorization: Bearer YOUR_V4V_API_KEY or x-api-key: YOUR_V4V_API_KEY.

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 methods use the same permissions, credits, rate limits and key revocation.

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.

1. Open your V4V profile and create a key under API Keys.
2. Save the key in your MCP client's secure settings.
3. Add the server using one of the configurations below.
4. Connect, inspect the available tools, and start with get_balance or list_models.

This preview supports clients that can send a custom Authorization or x-api-key header. It does not offer browser OAuth sign-in. A client that requires OAuth-only connections will need another connection method. Never paste your key into an assistant conversation or commit it to a repository.

Claude Web#

1. 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. In Claude, click +, open Connectors, and choose Add connector / Add custom 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#

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#

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.

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 or OAuth-only clients are not supported by this API-key connection.

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; a custom style description is also accepted.

{
  "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 generation or get_task, and project_name. 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.

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. 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": "Cinematic"
      }
    }
  ],
  "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.