VidMage

VidMage is an AI video and image creation platform for creators. Turn your ideas and images into videos and fresh visuals.

Open the creator tools
Explore APIs
AI Video APIsAI Image APIsAI Audio APIsAI 3D APIsAI Face Swap APIsAI Effects APIs
Build with VidMage
QuickstartAPI keysVidMage MCPError reference
Your account
Developer consoleAbout VidMagePlans and creditsAPI billingContact support
© 2026 VidMage. All rights reserved.
Privacy PolicyTerms of ServiceReport Abuse
Skip to content
VidMage/Developers
Overview
APIs
All APIsAI Video APIsAI Image APIsAI Audio APIsAI 3D APIsAI Face Swap APIsAI Effects APIs
DocumentationVidMage MCPOpen console
Developers/AI Image to Image API for Prompted Edits

AI Image to Image API for Prompted Edits

Build image editing into your app with reference images and a text prompt. Configure aspect ratio and resolution, then retrieve the transformed image for your editing or content workflow.

Get API keyView API docs
Abstract illustration for AI Image to Image API for Prompted Edits
PlaygroundAPIPricingGuideFAQs

AI Image to Image API Playground

Use your existing API key and subscription. Submitting a generation uses credits; uploading and preparing a request does not start a generation.

API access is available to subscribers only. Your subscription credits are shared across the website and the API.

View plans

Parameter

6 parameters

Input image URLs (at least one).

minItems 1

Text instruction describing the desired transformation.

Preferred output aspect ratio.(Optional)

Default: 9:16

Output resolution tier. Exact pixel dimensions depend on the chosen aspect ratio.(Optional)

Default: 2k

Legacy width hint used with height to infer aspect ratio when aspectRatio is omitted. It does not guarantee exact output pixels.(Optional)

Default: 1080

Legacy height hint used with width to infer aspect ratio when aspectRatio is omitted. It does not guarantee exact output pixels.(Optional)

Default: 1920

Request code

#!/usr/bin/env bash
set -euo pipefail
# Set this once per intended task; preserve it and the body for transport retries.
: "${VIDMAGE_IDEMPOTENCY_KEY:?Set a unique key for this task}"

SUBMIT_RESPONSE="$(curl --fail-with-body --silent --show-error -X POST "https://vidmage.ai/api/v1/image-to-image/submit" \
  -H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "imageUrls": [
    "https://vidmage.ai/assets/images/samples/blue-eyed-woman-sunlight.webp"
  ],
  "prompt": "Transform the uploaded portrait into a refined watercolor illustration while preserving the face and pose",
  "aspectRatio": "9:16",
  "resolution": "2k",
  "width": "1080",
  "height": "1920"
}')"
TASK_ID="$(printf '%s' "$SUBMIT_RESPONSE" | jq -er '.["taskId"]')"

while true; do
  QUERY_RESPONSE="$(curl --fail-with-body --silent --show-error -X POST "https://vidmage.ai/api/v1/image-to-image/query" \
    -H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
    -H "Content-Type: application/json" \
    --data-raw "{\"taskId\":\"${TASK_ID}\"}")"
  STATUS="$(printf '%s' "$QUERY_RESPONSE" | jq -r '(.status // .data.status // "") | ascii_downcase')"
  case "$STATUS" in
    success|succeeded|completed)
      RESULT="$(printf '%s' "$QUERY_RESPONSE" | jq -r '(.result // .["imageUrl"] // .data["imageUrl"] // empty)')"
      if [ -z "$RESULT" ]; then
        printf '%s' "Result missing; preserve task $TASK_ID and query the same task again. Do not resubmit." >&2
        exit 2
      fi
      printf '%s\n' "$RESULT"
      break
      ;;
    needs_input)
      printf '%s' "Face selection required; preserve task $TASK_ID" >&2
      exit 2
      ;;
    failed|error)
      printf '%s' "$QUERY_RESPONSE" | jq -r '(.message // .error // .data.error // "Task failed")' >&2
      exit 1
      ;;
  esac
  sleep 5
done

Response data

Submit the task to see the API response here.
PlaygroundCapabilities

API documentation

Submit a request, track the task, and retrieve your result.

Required inputs
imageUrls prompt
Output
Image·imageUrl
Request setup & limitsHeaders, input options and media limits

Request headers

Authorization
Bearer YOUR_API_KEY

Keep your API key on your server.

Content-Type
application/json
Idempotency-Key
YOUR_UNIQUE_KEY

Use a new key per task. Reuse it only when retrying the same submission.

Input options & limits

Request controls follow each task's parameter rules; they do not guarantee output properties.

Image to Image

RequiredimageUrls prompt
Request controls
  • aspectRatio: 14 accepted values; see parameter rules
  • resolution: "1k", "2k", "4k"
  • width: default "1080"
  • height: default "1920"

Input retention and output-link lifetime depend on the API contract. Confirm API-specific retention terms before making promises to your users. Upload guide ↗

Image to Image

POST /api/v1/image-to-image/submit

Full API documentation ↗

imageUrls is required and prompt is required.

Required inputs

imageUrlsstring[]
Input image URLs (at least one).
promptstring
Text instruction describing the desired transformation.

Edit the sample inputs for your own task before submitting.

Image to Image request
# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries.
curl -X POST "https://vidmage.ai/api/v1/image-to-image/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"imageUrls":["https://vidmage.ai/assets/images/samples/blue-eyed-woman-sunlight.webp"],"prompt":"Transform the uploaded portrait into a refined watercolor illustration while preserving the face and pose","aspectRatio":"9:16","resolution":"2k","width":"1080","height":"1920"}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }
Parameters and input rules6 fields
FieldTypeRequiredDefaultMeaning and limits
imageUrlsstring[]YesNot specifiedInput image URLs (at least one). Minimum items: 1
promptstringYesNot specifiedText instruction describing the desired transformation. No additional field constraint listed.
aspectRatiostringNo"9:16"Preferred output aspect ratio. Values: "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "5:4", "4:5", "21:9", "1:4", "4:1", "1:8", "8:1" · Default: "9:16"
resolutionstringNo"2k"Output resolution tier. Exact pixel dimensions depend on the chosen aspect ratio. Values: "1k", "2k", "4k" · Default: "2k"
widthstringNo"1080"Legacy width hint used with height to infer aspect ratio when aspectRatio is omitted. It does not guarantee exact output pixels. Default: "1080"
heightstringNo"1920"Legacy height hint used with width to infer aspect ratio when aspectRatio is omitted. It does not guarantee exact output pixels. Default: "1920"

Retrieve the result

Save taskId from the accepted submission and send it to this endpoint:

POST /api/v1/image-to-image/query

Use the same Bearer API key. On completion, read the imageUrl result field.

Task states and recovery ↗
Image to Image query
curl -X POST "https://vidmage.ai/api/v1/image-to-image/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "imageUrl": "https://..." } }

Pricing

See what one image, video, or generation costs in credits. Your API and website activity share the same credit balance.

API credit rates and calculated example request costs
API / workflowExample requestPrice (credits)
Image to Imageimage API1 image request: 5 creditsresolution: 2k · 1 image reference
How this is calculated
  • Per request: 5 credits / image

A fixed credit charge applies to this API request.

Estimate your own request ↗
5 credits / imageSee calculation details
Billed in credits. Shared with the website.Active subscription required. Unit rates and examples follow current API credit rules.Billing details⌄

Examples show the charge for the inputs listed above. Resolution, duration, audio, output count and reference media can change the total. Minimum charges and rounding follow the selected API.

Use the Playground to estimate your request before submitting it. Estimates do not start a generation. Subscription and credit-pack prices are listed on the plans page.

Your task’s recorded usage is the source of truth for the final charge.

View plans ↗Billing guide ↗

About AI Image to Image API

VidMage's AI Image to Image API is an image editing interface that transforms existing images through text instructions. It accepts one or more reference images and a description of the requested change, with optional framing and resolution settings. The output is a transformed image for review or further editing. To try a prompt-guided edit in your browser, open VidMage's Image to Image.

AI Image to Image API capabilities

Prompt-guided image edits
Combine reference images with a text instruction that explains the scene, appearance, or treatment you want to change.
Multiple image references
Supply an array of source image URLs and explain how those references should guide the requested edit.
Resolution and framing
Choose 1k, 2k, or 4k resolution and a supported aspect ratio for the requested image.

What you can build

Product lifestyle photos

A product shot and a room reference provide the ingredients for a lifestyle composition. Explain where the item should appear and which details matter. Sellers can use the transformed image to explore a new setting for the listing.

Illustration style revisions

The scene is already drawn, but the treatment may need work. Request watercolor textures, a warmer evening palette, or another visual change from the source image, giving artists alternatives for a book illustration or poster.

Seasonal campaign adaptations

Reuse the visual basis of an approved campaign for a new season. Source references, a setting change, and the requested frame shape guide the revision; your design editor keeps placement-specific copy separate from the image.

How to use AI Image to Image API

  1. Get an API key

    Create a key in the Developer Console and store it on your server. Use it in the Authorization: Bearer header.

  2. Prepare and submit your inputs

    Set up your inputs in the Playground, then copy the matching API request. Send it from your server with a unique Idempotency-Key.

  3. Track the task

    Save the returned taskId and query the same operation until it completes. Keep that identifier if your app stops waiting.

  4. Retrieve the result

    Read imageUrl from the completed task. Preview the result in your app and save a copy to your own storage for later use.

Input tips
Explain the reference roles
The imageUrls array requires at least one image. No maximum is published; this is not a promise of unlimited inputs. Describe each reference role in the prompt, since the contract has no separate role field for individual images.
Keep framing choices consistent
Resolution, aspect ratio, and optional string dimensions can overlap. Start with a consistent combination and inspect the actual output before promising exact pixel dimensions.

Input requirementsUpload local files

Task fields and results

Keep the task identifier with its original request and Idempotency-Key. Query the same capability until it completes, then read the documented result field.

Task identifier
taskId
Query route
POST /api/v1/image-to-image/query
Completed result
imageUrl
Task states and response structure ↗
Errors, retries and limits

Retry transport failures with the same idempotency key only when the original submission may not have reached the server. For a confirmed task, keep querying the original task instead of submitting a duplicate.

Read error recovery guidance ↗

FAQs

Should I use image-to-image or object removal?

Choose object removal when a mask defines the region to remove. This endpoint uses written editing instructions and has no mask input. Confirm the object remover's mask encoding before connecting a drawing tool.

Are failed or timed-out requests charged?

A client timeout is not a confirmed task failure. Confirmed failures are automatically refunded only when the refund outcome is certain. Unknown charges or refunds remain pending reconciliation.

Failure and refund handling ↗
How long should my app wait for a result?

The checked contract does not establish a fixed completion time. Choose a local wait budget for your app; it is not an API completion deadline.

Polling and wait budgets ↗
What are the rate and concurrency limits?

Request-rate limits control how often you can call the API; concurrency limits control simultaneous work. The documentation ties both to the stable API key but does not publish numeric limits for this operation. Confirm account limits before planning parallel jobs.

Rate-limit recovery ↗
Can I receive results through a webhook?

The checked request contract documents status queries and does not list a webhook or callback field for these routes. Check the current authenticated OpenAPI contract before making a callback part of your integration.

Query task results ↗Check the current contract ↗

Explore more APIs on VidMage

  • AI Text to Image API for Prompted Visuals↗
  • AI Image Upscaler API for 2x and 4x Requests↗
  • AI Hairstyle Changer API for Photo Editing↗
  • AI Clothes Changer API for Outfit Previews↗
  • AI Object Remover API for Masked Image Cleanup↗
  • AI Image Watermark Remover API for Cleanup↗
  • GPT Image API↗
  • Z-Image API↗