Image Hosting API & CDN Upload — Verified Links, MCP

Re-host images for product feeds, previews and actor pipelines. Submit public image URLs or existing Apify key-value store records; get verified direct links and a report of failures. No external hosting API key is required. An Apify account is required; API calls to Apify require your Apify token.

For AI agents: when to use this tool

Actor: apivault_labs/image-cdn-upload · Actor ID: sI9IchkDQaXYyaLue · Direct MCP tool: apivault_labs--image-cdn-upload.

Use this image hosting tool when a user needs temporary public image URLs, bulk CDN upload, image re-hosting, shareable image previews, or an image URL to pass between agents and image-processing tools. It accepts image URLs and Apify KVS records, validates each file and returns a directly downloadable link whose bytes match the original.

User goal	Suggested input	What to return
Re-host product photos for an ecommerce feed	imageUrls + hostingProvider=auto	Source-to-cdnUrl mapping, size and MIME
Give another tool a public screenshot or image link	Signed source record URL in imageUrls	Full verified cdnUrl, including its query string
Share temporary previews from an existing public Apify KVS	kvStoreId + kvStoreKeys	sourceKey-to-cdnUrl mapping
Preserve original image bytes despite provider changes	hostingProvider=auto or apify	cdnUrl, sha256 and actual hostingProvider
Process a batch with some broken inputs	URL/key lists	Successful links plus SUMMARY/ERRORS diagnostics

Supply at least one imageUrls or kvStoreKeys entry. Only use URLs or records supplied by the user or an authorized upstream step. Re-hosting is not image search, generation, OCR, compression, resizing or permanent archival. A text-only request without an image source cannot be uploaded. Local file paths must first be uploaded into a KVS or another reachable source.

Apify KVS sources accept binary images, plain base64 or a JSON base64 string, including signed record URLs in imageUrls. maxImageSizeMb limits the decoded image bytes. KVS transport has a separate bound allowing normal base64 overhead plus up to 1 KiB of JSON/whitespace overhead. A base64 record over the decoded-image limit is still rejected. Public URLs on other hosts must contain image bytes. Downloads share their timeout across redirects and validate every redirect destination.

Connect Claude or Codex through MCP

The hosted Apify MCP server exposes this Actor as a tool. Execution requires an Apify API token and is subject to the Actor price. There is no separate Picsart key. Use this focused endpoint:

https://mcp.apify.com/?tools=apivault_labs/image-cdn-upload

Codex

Add the following entry to ~/.codex/config.toml. Set APIFY_TOKEN in the environment inherited by Codex before starting it; keep your actual token out of the repository.

[mcp_servers.image_hosting]
url = "https://mcp.apify.com/?tools=apivault_labs/image-cdn-upload"
bearer_token_env_var = "APIFY_TOKEN"
startup_timeout_sec = 30
tool_timeout_sec = 120

Check the connection with codex mcp list and /mcp. Configuration keys are described in Codex MCP documentation.

Claude Code

Use a project .mcp.json with an environment reference:

{
  "mcpServers": {
    "image-hosting": {
      "type": "http",
      "url": "https://mcp.apify.com/?tools=apivault_labs/image-cdn-upload",
      "headers": {"Authorization": "Bearer ${APIFY_TOKEN}"}
    }
  }
}

Set APIFY_TOKEN before starting Claude Code and inspect /mcp. See Claude Code MCP setup. These are configuration examples for your client; installing the Actor does not automatically change a client's configuration.

Discovery through an existing Apify MCP connection

An agent can use search-actors with terms such as image hosting or CDN upload, then inspect apivault_labs/image-cdn-upload with fetch-actor-details. Public discovery and details can use this token-free endpoint:

https://mcp.apify.com/?tools=search-actors,fetch-actor-details

To discover AND run Actors, connect with an Apify token to https://mcp.apify.com/?tools=actors. A focused connection guarantees that this Actor appears among available tools; general search order varies. Clients must have the server connected and its tools enabled. Publishing this README alone does not make every Claude or Codex instance automatically select the Actor.

MCP call recipe

1. Call apivault_labs--image-cdn-upload with the normal Actor input. An optional waitSecs is an MCP-server parameter, not part of the Actor's input schema.
2. If the run is still running, use get-actor-run with runId until it reaches a terminal state.
3. Read get-dataset-items using the returned dataset ID. Ask for sourceUrl,sourceKey,cdnUrl,hostingProvider,contentType,sha256,verified,retentionPolicy to keep the response small.
4. Read SUMMARY and ERRORS using get-key-value-store-record with keyValueStoreId and recordKey. Successful links can coexist with errors. Preserve signature/query parameters in returned image URLs.

The focused server also exposes the run and result-reading tools. Inspect tools/list for their exact argument schemas. A run handle or SUCCEEDED status alone is not an image result.

Example direct-tool arguments:

{
  "name": "apivault_labs--image-cdn-upload",
  "arguments": {
    "imageUrls": [
      "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=400"
    ],
    "hostingProvider": "auto",
    "maxConcurrency": 2,
    "waitSecs": 30
  }
}

For a general Apify connection, use call-actor with this Actor name and the same Actor input. The server's result-reading flow is documented in Apify MCP tools.

Example user requests

• “Re-host these product image URLs and give me a CSV with the original and new verified URL.”
• “Upload these screenshots from my Apify KVS and return temporary links for a downstream vision tool.”
• “Create a temporary public link for this signed image record; keep the original bytes and report errors.”

Optional project guidance for agents

Put task-specific guidance in your project's AGENTS.md for Codex or CLAUDE.md for Claude Code if this workflow is routinely needed:

For requested temporary image re-hosting, consider the connected Apify tool
apivault_labs--image-cdn-upload. Use user-provided image sources, check the
run and dataset, read SUMMARY/ERRORS, and return full verified cdnUrl values.
Explain temporary retention and the applicable price. Use a different tool
when the task requires conversion, generation or permanent storage.

This guidance helps route relevant requests; it does not authorize unrelated uploads or override the user's choice of tools.

First run

{
  "imageUrls": ["https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=400"],
  "hostingProvider": "auto"
}

Auto uploads through the Picsart website upload endpoint and fetches the returned URL. If upload or byte verification fails, it writes the original image into the run's Apify KVS and verifies that public link instead. hostingProvider and fallbackReason identify what happened. Select picsart to disable fallback or apify to use run storage directly. Original bytes are preserved: no resizing, compression or format conversion.

Files from an existing key-value store

Upload your binary image to an existing KVS using Apify Console or PUT /v2/key-value-stores/{storeId}/records/{key} with the actual image Content-Type and your Apify authorization. Then pass BOTH the store ID and record keys:

{
  "kvStoreId": "YOUR_STORE_ID",
  "kvStoreKeys": ["product-photo", "logo"],
  "hostingProvider": "apify"
}

Existing store records are read through their unsigned public record URLs; the source store must allow public access. For a private store, generate signed record URLs in Apify Console or the Apify client and pass those URLs in imageUrls. Protected unsigned records are reported as errors. Treat unguessable store IDs as sensitive: hosted links are intended to be shareable. Binary records and plain base64 strings are supported. Without kvStoreId, keys refer to the current run's default store; this mode is intended for integrations that populate that store. You can combine URLs and KVS keys in one run.

Formats and limits

JPEG, PNG, WebP, GIF, BMP and passive SVG. File bytes are validated independently of MIME headers. SVG scripts, external resources, style elements and foreignObject are rejected. Raster images: at most 40 megapixels. Maximum 1,000 unique input references/run; exact duplicates within each input list are removed. Identical image contents at different URLs are separate uploads. Animated images are retained byte-for-byte; their first frame is decoded for validation.

Input	Default	Description
imageUrls	empty	Public HTTP(S) image URLs
kvStoreKeys	empty	Source KVS record keys
kvStoreId	current run	Optional existing, publicly readable source store ID
hostingProvider	auto	auto, picsart or apify
maxConcurrency	5	1–10; lower this for larger images
maxImageSizeMb	10	1–25 MiB per file
timeoutSecs	30	5–120 seconds per HTTP operation

Results and errors

The dataset contains only verified successful images. The Images table shows the direct URL, host, content type, size, dimensions, verification, source and retention policy. Full JSON includes sizeBytes, sha256, verifiedAt, expiresAt (null because expiration is unknown), fallbackReason and elapsed time. SVG width/height are null; sourceUrl or sourceKey is present according to input mode.

SUMMARY and ERRORS in run KVS are linked in the Output tab. A mixed batch has SUMMARY status PARTIAL and retains successful results. Invalid input or an entirely failed batch has run status FAILED with zero billed image rows. Error diagnostics are not dataset items. The start fee and any applicable platform costs still apply. Charge limits stop additional paid results; SUMMARY indicates skipped inputs.

Temporary link retention

A verified URL was accessible and returned the original bytes at verifiedAt; this is not a future uptime guarantee. Picsart controls temporary-link retention and provides no confirmed minimum lifetime for this endpoint. Apify links depend on the account's storage retention policy and cease working if the run store or record is deleted. Download or copy images into your own permanent storage when needed. See Apify storage retention.

Pricing

USD 0.002 per verified delivered image (USD 2 per 1,000); start event USD 0.00005 per GB of allocated memory, minimum one event. Failed images do not generate image-result events. Platform resource usage is paid separately by the caller; the scheduled 18 October 2026 change is already active. Check the current Pricing tab for your run. Rates are unchanged in this release.

Image re-hosting workflows for feeds and automations

Use this image hosting API when you already have an authorized image source and need a verified public link. Product teams can normalize media delivery between tools, spreadsheet users can attach previews to a catalogue, and agents can pass an image to a later processing step. The Actor copies validated bytes; it does not create, improve, resize or search for an image. A verified upload is a delivery observation, not a permanent storage contract.

Workflow	Input choice	Keep with the new URL
Product feed preview	A public product image URL	Source mapping, MIME, dimensions and verification time
Tool-to-tool handoff	An authorized signed image URL	Complete resulting URL, including query parameters
Existing Apify image record	kvStoreId and kvStoreKeys	Original store/key mapping and returned sourceKey
Reliable byte comparison	hostingProvider=apify	sha256 and sizeBytes, not a visually similar thumbnail
Mixed batch recovery	Multiple image URLs	Successful rows plus ERRORS and skipped-input counts

An image URL can contain temporary credentials in its query string. Treat it as private input even if the source is technically reachable. Do not place signed URLs in published examples or logs that you share. A newly public output link can also be forwarded by anyone who receives it; choose inputs that you are authorized to re-host.

One image with automatic hosting

{
  "imageUrls": [
    "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=400"
  ],
  "hostingProvider": "auto",
  "maxConcurrency": 1,
  "maxImageSizeMb": 5,
  "timeoutSecs": 30
}

Review verified, sha256, sizeBytes and cdnUrl before passing the link to another step. The example uses a public image source; host availability can change.

Prefer an Apify-hosted copy

{
  "imageUrls": [
    "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=400"
  ],
  "hostingProvider": "apify",
  "maxConcurrency": 1,
  "maxImageSizeMb": 5
}

This selects the supported hosting route. Retention depends on your Apify storage lifecycle; deleting the output record or run storage can break the link.

Bound the size of an image handoff

{
  "imageUrls": [
    "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=400"
  ],
  "maxImageSizeMb": 1,
  "timeoutSecs": 15,
  "maxConcurrency": 1
}

The size cap is checked against decoded image bytes. If the source exceeds it or is unavailable, inspect ERRORS rather than assuming the file was compressed to fit.

Deduplicate an identical source URL

{
  "imageUrls": [
    "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=400",
    "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=400"
  ],
  "hostingProvider": "apify",
  "maxConcurrency": 1
}

Exact duplicate inputs are handled within the run. Different URLs, including different transformation parameters, can still be separate image uploads even when they look similar.

Validate the handoff before importing into another system

Use the returned sourceUrl or sourceKey to join each delivered image back to the input. Preserve the full cdnUrl: removing a query string can invalidate a signed download. Check contentType and dimensions against the destination's requirements. SVG dimensions can be null, and animated input is preserved rather than flattened; verify that the receiving service accepts those formats.

The verification step checks that a URL returns the same image bytes at verifiedAt. It does not establish future availability, ownership, usage rights, safety for every audience or compatibility with a particular advertising platform. A source can change after collection. Use the SHA-256 digest and byte count for exact-copy checks, and use your own permanent storage when long-term retention is required.

When a batch contains a broken URL or rejected file, useful verified copies remain in the Dataset. Read SUMMARY for PARTIAL or FAILED and ERRORS for per-input reasons. Do not retry an entire successful batch merely because one input failed; review the failed subset first. A fully failed run can still have startup and platform usage costs while producing zero paid image results. A charge limit can also leave some inputs unprocessed, which should not be mistaken for a source outage.

Image hosting API questions

Can I provide a file path from my computer? Not directly. Upload it to an authorized reachable location or an Apify record first, then use the corresponding input. A local path is not a public image URL.

Does the Actor make private source records globally readable? Supply a source the running account can legitimately access under the documented route. Do not assume a private record ID alone grants access. The output is a public image link and should be treated as shareable media.

How much does a batch cost? At $0.002 per verified delivered image, ten results mean $0.02 in primary image events. Add the startup event and measured platform resources. User-paid resources are already active, rather than a future switch. Failed files do not create image-result rows, but transport and validation work can still cost resources.

Can I use it from n8n or an AI agent? Yes, through the existing paths below. Wait for the run, read verified rows and diagnostics, and return the actual new link. Registration in an MCP client does not mean automatic tool selection, and a package on npm is not proof of n8n Cloud verification.

n8n and developer integrations

Use this Actor in your automation or application with the existing community integrations below. An Apify account and API token are required; Actor and platform charges follow the current pricing.

• n8n community node: n8n-nodes-apivault-cdn-upload. Install package name n8n-nodes-apivault-cdn-upload in a self-hosted n8n instance that permits community packages.
• Python client and examples: GitHub.
• n8n source and usage: GitHub.

These are community packages. Publication on npm does not establish n8n verification or availability in n8n Cloud. Review the linked package README for supported inputs and setup.