GPT Image API

Add GPT Image generation and editing to your app through VidMage. Use dedicated API routes for text generation or source-image edits, with canvas controls and reference-image limits specific to each capability.

Get API key View API docs

GPT 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.

Choose a task

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

View plans

Parameter

3 parameters

prompt*string

Text prompt describing the image to generate (max 20000 chars). For an unspecified character or figurine, use an original non-branded character with no logos and no resemblance to existing copyrighted superheroes; preserve any character the user explicitly names.

aspectRatioOptionalstring

Output aspect ratio.(Optional)

modelOptionalstring

Choose the GPT image model generation tier.(Optional)

Default: g-4.2

API key

Loading…

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/gpt-image-generator/submit" \
  -H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "prompt": "Clean product photograph of a minimalist ceramic desk lamp on a warm neutral background",
  "model": "g-4.2"
}')"
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/gpt-image-generator/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

API documentation

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

EndpointGPT Image Generator

Required inputs: prompt
Output: ImageimageUrl

EndpointGPT Image 2 Generator

Required inputs: prompt
Output: ImageimageUrl

EndpointGPT Image 2.5 Generator

Required inputs: prompt
Output: ImageimageUrl

EndpointGPT Image 2 Image to Image

Required inputs: imageUrls prompt
Output: ImageimageUrl

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.

GPT Image Generator

Modes: text-to-image

Requiredprompt

Request controls

aspectRatio: "960x960", "720x1280", "1280x720", "1168x784", "784x1168"
model: "g-3", "g-4", "g-4.1", "g-4.2"

GPT Image 2 Generator

Modes: text-to-image

Requiredprompt

Request controls

aspectRatio: 15 accepted values; see parameter rules
resolution: "1k", "2k", "4k"

GPT Image 2.5 Generator

Modes: text-to-image, image-edit

Additional inputs; requirements vary by mode

prompt imageUrl imageUrls

Media limits by mode

Image EditImage: jpg, jpeg, png; up to 10 MB per file; up to 16 files

Request controls

aspectRatio: 15 accepted values; see parameter rules
resolution: "1k", "2k", "4k"

GPT Image 2 Image to Image

RequiredimageUrls prompt

Media limits by mode

imageUrlsUp to 2 items.

Request controls

aspectRatio: "3:2", "1:1", "2:3"

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

GPT Image Generator

POST /api/v1/gpt-image-generator/submit

Full API documentation ↗

prompt is required.

Required inputs

promptstring: Text prompt describing the image to generate (max 20000 chars). For an unspecified character or figurine, use an original non-branded character with no logos and no resemblance to existing copyrighted superheroes; preserve any character the user explicitly names.

Edit the sample inputs for your own task before submitting.

GPT Image Generator 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/gpt-image-generator/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Clean product photograph of a minimalist ceramic desk lamp on a warm neutral background","aspectRatio":"1280x720","model":"g-4.2"}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }

Parameters and input rules3 fields

Field	Type	Required	Default	Meaning and limits
`prompt`	`string`	Yes	Not specified	Text prompt describing the image to generate (max 20000 chars). For an unspecified character or figurine, use an original non-branded character with no logos and no resemblance to existing copyrighted superheroes; preserve any character the user explicitly names. Minimum length: 1 · Maximum length: 20000
`aspectRatio`	`string`	No	Not specified	Output aspect ratio. Values: "960x960", "720x1280", "1280x720", "1168x784", "784x1168"
`model`	`string`	No	`"g-4.2"`	Choose the GPT image model generation tier. Values: "g-3", "g-4", "g-4.1", "g-4.2" · Default: "g-4.2"

Mode-specific fields & media limits

Text To Image rules

Control	Mode-specific rule
`prompt`	Required; minimum 1 characters; maximum 20000 characters
`aspectRatio`	Values: "960x960", "720x1280", "1280x720", "1168x784", "784x1168"; mode default: "1280x720"
`model`	Values: "g-3", "g-4", "g-4.1", "g-4.2"; Default: "g-4.2"

Retrieve the result

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

POST /api/v1/gpt-image-generator/query

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

Task states and recovery ↗

GPT Image Generator query

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

GPT Image 2 Generator

POST /api/v1/gpt-image-2-generator/submit

Full API documentation ↗

prompt is required.

Required inputs

promptstring: Text prompt describing the image to generate (max 20000 chars). For an unspecified character or figurine, use an original non-branded character with no logos and no resemblance to existing copyrighted superheroes; preserve any character the user explicitly names.

Edit the sample inputs for your own task before submitting.

GPT Image 2 Generator 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/gpt-image-2-generator/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A friendly home robot watering herbs in a bright Scandinavian kitchen, realistic lifestyle photography","aspectRatio":"16:9","resolution":"1k"}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }

Parameters and input rules3 fields

Field	Type	Required	Default	Meaning and limits
`prompt`	`string`	Yes	Not specified	Text prompt describing the image to generate (max 20000 chars). For an unspecified character or figurine, use an original non-branded character with no logos and no resemblance to existing copyrighted superheroes; preserve any character the user explicitly names. Minimum length: 1 · Maximum length: 20000
`aspectRatio`	`string`	No	`"16:9"`	Output aspect ratio. Values: "1:1", "3:2", "2:3", "5:4", "4:5", "16:9", "9:16", "21:9", "3:4", "4:3", "9:21", "1:2", "2:1", "1:3", "3:1" · Default: "16:9"
`resolution`	`string`	No	`"1k"`	Output resolution tier. Values: "1k", "2k", "4k" · Default: "1k"

Mode-specific fields & media limits

Text To Image rules

Control	Mode-specific rule
`prompt`	Required; minimum 1 characters; maximum 20000 characters
`aspectRatio`	Values: "1:1", "3:2", "2:3", "5:4", "4:5", "16:9", "9:16", "21:9", "3:4", "4:3", "9:21", "1:2", "2:1", "1:3", "3:1"; mode default: "16:9"
`resolution`	Values: "1k", "2k", "4k"; mode default: "1k"

Retrieve the result

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

POST /api/v1/gpt-image-2-generator/query

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

Task states and recovery ↗

GPT Image 2 Generator query

curl -X POST "https://vidmage.ai/api/v1/gpt-image-2-generator/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "imageUrl": "https://..." } }

GPT Image 2.5 Generator

POST /api/v1/gpt-image-2-5-generator/submit

Full API documentation ↗

prompt is required.

Required inputs

promptstring: Text prompt describing the image to generate (max 32000 chars). For an unspecified character or figurine, use an original non-branded character with no logos and no resemblance to existing copyrighted superheroes; preserve any character the user explicitly names.

Edit the sample inputs for your own task before submitting.

GPT Image 2.5 Generator 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/gpt-image-2-5-generator/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A refined botanical poster with a sage ceramic vase, fern fronds, and the exact headline FERN in dark green type on ivory paper","aspectRatio":"16:9","resolution":"1k"}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }

Parameters and input rules5 fields

Field	Type	Required	Default	Meaning and limits
`prompt`	`string`	Yes	Not specified	Text prompt describing the image to generate (max 32000 chars). For an unspecified character or figurine, use an original non-branded character with no logos and no resemblance to existing copyrighted superheroes; preserve any character the user explicitly names. Minimum length: 2 · Maximum length: 32000
`imageUrl`	`string`	No	Not specified	Optional input image URL. When provided, the task runs in image edit mode. No additional field constraint listed.
`imageUrls`	`string[]`	No	Not specified	Ordered input image URLs for image editing mode. The prompt can reference them by their one-based order. Minimum items: 1 · Maximum items: 16
`aspectRatio`	`string`	No	`"16:9"`	Output aspect ratio. Values: "1:1", "3:2", "2:3", "5:4", "4:5", "16:9", "9:16", "21:9", "3:4", "4:3", "9:21", "1:2", "2:1", "1:3", "3:1" · Default: "16:9"
`resolution`	`string`	No	`"1k"`	Output resolution tier. Values: "1k", "2k", "4k" · Default: "1k"

Mode-specific fields & media limits

Text To Image rules

Control	Mode-specific rule
`prompt`	Required; minimum 2 characters; maximum 32000 characters
`aspectRatio`	Values: "1:1", "3:2", "2:3", "5:4", "4:5", "16:9", "9:16", "21:9", "3:4", "4:3", "9:21", "1:2", "2:1", "1:3", "3:1"; mode default: "16:9"
`resolution`	Values: "1k", "2k", "4k"; mode default: "1k"

Image Edit rules

Control	Mode-specific rule
`prompt`	Required; minimum 2 characters; maximum 32000 characters
`aspectRatio`	Values: "1:1", "3:2", "2:3", "5:4", "4:5", "16:9", "9:16", "21:9", "3:4", "4:3", "9:21", "1:2", "2:1", "1:3", "3:1"; mode default: "16:9"
`resolution`	Values: "1k", "2k", "4k"; mode default: "1k"
`imageUrls`	Image input; up to 16 items

Retrieve the result

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

POST /api/v1/gpt-image-2-5-generator/query

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

Task states and recovery ↗

GPT Image 2.5 Generator query

curl -X POST "https://vidmage.ai/api/v1/gpt-image-2-5-generator/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "imageUrl": "https://..." } }

GPT Image 2 Image to Image

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

Full API documentation ↗

imageUrls is required and prompt is required.

Required inputs

imageUrlsstring[]: One or two source image URLs.
promptstring: Image editing instruction (5-800 characters).

Edit the sample inputs for your own task before submitting.

GPT Image 2 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/gpt-image-2-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":"Turn the scene into a polished winter evening while preserving the main subject and composition","aspectRatio":"1:1"}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }

Parameters and input rules3 fields

Field	Type	Required	Default	Meaning and limits
`imageUrls`	`string[]`	Yes	Not specified	One or two source image URLs. Minimum items: 1 · Maximum items: 2
`prompt`	`string`	Yes	Not specified	Image editing instruction (5-800 characters). Minimum length: 5 · Maximum length: 800
`aspectRatio`	`string`	No	`"1:1"`	Output aspect ratio. Values: "3:2", "1:1", "2:3" · Default: "1:1"

Retrieve the result

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

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

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

Task states and recovery ↗

GPT Image 2 Image to Image query

curl -X POST "https://vidmage.ai/api/v1/gpt-image-2-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 / workflow	Example request	Price (credits)
GPT Image Generatorimage API	1 image request: 5 credits How this is calculated Base rate: 5 credits / generation Base charge is per generation at the selected resolution. Estimate your own request ↗	5 credits / generationSee calculation details
GPT Image 2 Generatorimage API	1 image request: 5 creditsresolution: 1k How this is calculated 1k: 5 credits / generation 2k: 5 credits / generation 4k: 5 credits / generation Base charge is per generation at the selected resolution. Estimate your own request ↗	5 credits / generationSee calculation details
GPT Image 2.5 Generatorimage API	1 image request: 5 creditsresolution: 1k How this is calculated 1k: 5 credits / generation 2k: 10 credits / generation 4k: 15 credits / generation Base charge is per generation at the selected resolution. Each reference image adds 1 credit. Estimate your own request ↗	5–15 credits / generationBase rate varies by settings or workflow
GPT Image 2 Image to Imageimage API	1 image request: 5 credits1 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 GPT Image API

VidMage's GPT Image API is an image generation and editing interface with separate capabilities for text prompts and source images. The selected capability determines canvas controls, prompt requirements, and reference capacity. The standalone edit capability accepts one or two images, while GPT Image 2.5 editing supports up to sixteen sources. To explore this model's browser workflow, open VidMage's GPT Image Generator.

GPT Image API capabilities

Generate images from text: GPT Image Generator and GPT Image 2 Generator list text generation only. Use their accepted canvas settings for a new composition; choose an editing capability for source images.
Make a focused source edit: Use the standalone image-to-image capability with one or two source images and a concise change instruction.
Edit with a larger reference set: Choose the GPT Image 2.5 edit mode when your request needs its larger source-image capacity.

What you can build

Custom slide illustrations

Illustrate the actual subject of a presentation, such as a warehouse packing station, from a slide brief and accepted canvas settings. Add labels separately so they stay editable.

Product photo revisions

Sellers can request a different setting or lighting treatment for a photo they already use. An editing capability takes the source and change instruction, producing a version they can compare before deciding whether to update the listing.

Campaign reference compositions

Art directors often bring product, wardrobe, and location references to the same brief. Send the collection to an editing capability that accepts its size, with clear roles for the sources, to explore how those elements could work in one campaign image.

How to use GPT Image API

Get an API key
Create a key in the Developer Console and store it on your server. Use it in the Authorization: Bearer header.
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.
Track the task
Save the returned taskId and query the same operation until it completes. Keep that identifier if your app stops waiting.
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

Read the canvas field values: The original GPT Image route puts pixel dimensions in aspectRatio. GPT Image 2 and 2.5 use ratio labels plus resolution; the standalone edit route has three ratios.
Match the source set to the route: The standalone edit route requires one or two images and a 5 to 800 character prompt. GPT Image 2.5 editing allows up to sixteen source images.

Input requirements Upload 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/gpt-image-generator/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

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 ↗

#!/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/gpt-image-generator/submit" \ -H "Authorization: Bearer ${VIDMAGE_API_KEY}" \ -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \ -H "Content-Type: application/json" \ --data-raw '{ "prompt": "Clean product photograph of a minimalist ceramic desk lamp on a warm neutral background", "model": "g-4.2" }')" 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/gpt-image-generator/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

# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries. curl -X POST "https://vidmage.ai/api/v1/gpt-image-generator/submit" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \ -H "Content-Type: application/json" \ -d '{"prompt":"Clean product photograph of a minimalist ceramic desk lamp on a warm neutral background","aspectRatio":"1280x720","model":"g-4.2"}' # -> { "success": true, "taskId": "...", "creditsConsumed": ... }

Field

Type

Required

Default

Meaning and limits

prompt

string

Yes

Not specified

aspectRatio

string

Not specified

Output aspect ratio. Values: "960x960", "720x1280", "1280x720", "1168x784", "784x1168"

model

string

"g-4.2"

Choose the GPT image model generation tier. Values: "g-3", "g-4", "g-4.1", "g-4.2" · Default: "g-4.2"

Control

Mode-specific rule

prompt

Required; minimum 1 characters; maximum 20000 characters

aspectRatio

Values: "960x960", "720x1280", "1280x720", "1168x784", "784x1168"; mode default: "1280x720"

model

Values: "g-3", "g-4", "g-4.1", "g-4.2"; Default: "g-4.2"

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

# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries. curl -X POST "https://vidmage.ai/api/v1/gpt-image-2-generator/submit" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \ -H "Content-Type: application/json" \ -d '{"prompt":"A friendly home robot watering herbs in a bright Scandinavian kitchen, realistic lifestyle photography","aspectRatio":"16:9","resolution":"1k"}' # -> { "success": true, "taskId": "...", "creditsConsumed": ... }

Field

Type

Required

Default

Meaning and limits

prompt

string

Yes

Not specified

aspectRatio

string

"16:9"

Output aspect ratio. Values: "1:1", "3:2", "2:3", "5:4", "4:5", "16:9", "9:16", "21:9", "3:4", "4:3", "9:21", "1:2", "2:1", "1:3", "3:1" · Default: "16:9"

resolution

string

"1k"

Output resolution tier. Values: "1k", "2k", "4k" · Default: "1k"

Control

Mode-specific rule

prompt

Required; minimum 1 characters; maximum 20000 characters

aspectRatio

Values: "1:1", "3:2", "2:3", "5:4", "4:5", "16:9", "9:16", "21:9", "3:4", "4:3", "9:21", "1:2", "2:1", "1:3", "3:1"; mode default: "16:9"

resolution

Values: "1k", "2k", "4k"; mode default: "1k"

curl -X POST "https://vidmage.ai/api/v1/gpt-image-2-generator/query" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }' # -> { "success": true, "data": { "status": "...", "imageUrl": "https://..." } }

# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries. curl -X POST "https://vidmage.ai/api/v1/gpt-image-2-5-generator/submit" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \ -H "Content-Type: application/json" \ -d '{"prompt":"A refined botanical poster with a sage ceramic vase, fern fronds, and the exact headline FERN in dark green type on ivory paper","aspectRatio":"16:9","resolution":"1k"}' # -> { "success": true, "taskId": "...", "creditsConsumed": ... }

Field

Type

Required

Default

Meaning and limits

prompt

string

Yes

Not specified

Text prompt describing the image to generate (max 32000 chars). For an unspecified character or figurine, use an original non-branded character with no logos and no resemblance to existing copyrighted superheroes; preserve any character the user explicitly names. Minimum length: 2 · Maximum length: 32000

imageUrl

string

Not specified

Optional input image URL. When provided, the task runs in image edit mode. No additional field constraint listed.

imageUrls

string[]

Not specified

Ordered input image URLs for image editing mode. The prompt can reference them by their one-based order. Minimum items: 1 · Maximum items: 16

aspectRatio

string

"16:9"

Output aspect ratio. Values: "1:1", "3:2", "2:3", "5:4", "4:5", "16:9", "9:16", "21:9", "3:4", "4:3", "9:21", "1:2", "2:1", "1:3", "3:1" · Default: "16:9"

resolution

string

"1k"

Output resolution tier. Values: "1k", "2k", "4k" · Default: "1k"

Control

Mode-specific rule

prompt

Required; minimum 2 characters; maximum 32000 characters

aspectRatio

Values: "1:1", "3:2", "2:3", "5:4", "4:5", "16:9", "9:16", "21:9", "3:4", "4:3", "9:21", "1:2", "2:1", "1:3", "3:1"; mode default: "16:9"

resolution

Values: "1k", "2k", "4k"; mode default: "1k"

Control

Mode-specific rule

prompt

Required; minimum 2 characters; maximum 32000 characters

aspectRatio

Values: "1:1", "3:2", "2:3", "5:4", "4:5", "16:9", "9:16", "21:9", "3:4", "4:3", "9:21", "1:2", "2:1", "1:3", "3:1"; mode default: "16:9"

resolution

Values: "1k", "2k", "4k"; mode default: "1k"

imageUrls

Image input; up to 16 items

curl -X POST "https://vidmage.ai/api/v1/gpt-image-2-5-generator/query" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }' # -> { "success": true, "data": { "status": "...", "imageUrl": "https://..." } }

# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries. curl -X POST "https://vidmage.ai/api/v1/gpt-image-2-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":"Turn the scene into a polished winter evening while preserving the main subject and composition","aspectRatio":"1:1"}' # -> { "success": true, "taskId": "...", "creditsConsumed": ... }

Field

Type

Required

Default

Meaning and limits

imageUrls

string[]

Yes

Not specified

One or two source image URLs. Minimum items: 1 · Maximum items: 2

prompt

string

Yes

Not specified

Image editing instruction (5-800 characters). Minimum length: 5 · Maximum length: 800

aspectRatio

string

"1:1"

Output aspect ratio. Values: "3:2", "1:1", "2:3" · Default: "1:1"

curl -X POST "https://vidmage.ai/api/v1/gpt-image-2-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://..." } }

API / workflow

Example request

Price (credits)

GPT Image Generatorimage API

1 image request: 5 credits

How this is calculated

Base rate: 5 credits / generation

Base charge is per generation at the selected resolution.

Estimate your own request ↗

5 credits / generationSee calculation details

GPT Image 2 Generatorimage API

1 image request: 5 creditsresolution: 1k

How this is calculated

1k: 5 credits / generation
2k: 5 credits / generation
4k: 5 credits / generation

Base charge is per generation at the selected resolution.

Estimate your own request ↗

5 credits / generationSee calculation details

GPT Image 2.5 Generatorimage API

1 image request: 5 creditsresolution: 1k

How this is calculated

1k: 5 credits / generation
2k: 10 credits / generation
4k: 15 credits / generation

Base charge is per generation at the selected resolution.

Each reference image adds 1 credit.

Estimate your own request ↗

5–15 credits / generationBase rate varies by settings or workflow

GPT Image 2 Image to Imageimage API

1 image request: 5 credits1 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

Read the canvas field values: The original GPT Image route puts pixel dimensions in aspectRatio. GPT Image 2 and 2.5 use ratio labels plus resolution; the standalone edit route has three ratios.
Match the source set to the route: The standalone edit route requires one or two images and a 5 to 800 character prompt. GPT Image 2.5 editing allows up to sixteen source images.

Input requirements Upload local files

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/gpt-image-generator/query

Completed result

imageUrl

Task states and response structure ↗

Read error recovery guidance ↗

GPT Image API

GPT Image API Playground

Parameter

Request code

API documentation

Request headers

Input options & limits

GPT Image Generator

GPT Image 2 Generator

GPT Image 2.5 Generator

GPT Image 2 Image to Image

Required inputs

Text To Image rules

Retrieve the result

Required inputs

Text To Image rules

Retrieve the result

Required inputs

Text To Image rules

Image Edit rules

Retrieve the result

Required inputs

Retrieve the result

Pricing

GPT Image API capabilities

Custom slide illustrations

Product photo revisions

Campaign reference compositions

Get an API key

Prepare and submit your inputs

Track the task

Retrieve the result

Explore more APIs on VidMage

GPT Image API

GPT Image API Playground

Parameter

Request code

API documentation

Request headers

Input options & limits

GPT Image Generator

GPT Image 2 Generator

GPT Image 2.5 Generator

GPT Image 2 Image to Image

Required inputs

Text To Image rules

Retrieve the result

Required inputs

Text To Image rules

Retrieve the result

Required inputs

Text To Image rules

Image Edit rules

Retrieve the result

Required inputs

Retrieve the result

Pricing

GPT Image API capabilities

Custom slide illustrations

Product photo revisions

Campaign reference compositions

Get an API key

Prepare and submit your inputs

Track the task

Retrieve the result

Explore more APIs on VidMage