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 3D Generation API

AI 3D Generation API

Build 3D asset generation into your app using text prompts, a reference image, or a single four-view image sheet. Select the matching endpoint and retrieve the generated model.

Get API keyView API docs
Abstract illustration for AI 3D Generation API
PlaygroundAPIPricingGuideFAQs

AI 3D Generation 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

1 Parameter

Public HTTP(S) URL, fileUrl returned by upload_files, or Base64 Data URI (PNG, JPEG, or WebP; max 128 KB) of a source image with one clearly visible subject or object.

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/ai-image-to-3d-model/submit" \
  -H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "imageUrl": "https://vidmage.ai/assets/images/ai-tools/ai-3d-model-detail-2.webp"
}')"
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/ai-image-to-3d-model/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 // .["modelUrl"] // .data["modelUrl"] // 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.

EndpointImage to 3D Model ↓
Required inputs
imageUrl
Output
3d·modelUrl
EndpointFour-View Image to 3D Model ↓
Required inputs
imageUrl
Output
3d·modelUrl
EndpointText to 3D Model ↓
Required inputs
prompt
Output
3d·modelUrl
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 3D Model

RequiredimageUrl

Output dimensions and format are not specified in this reference.

Four-View Image to 3D Model

RequiredimageUrl

Output dimensions and format are not specified in this reference.

Text to 3D Model

Requiredprompt

Output dimensions and format are not specified in this reference.

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 3D Model

POST /api/v1/ai-image-to-3d-model/submit

Full API documentation ↗

imageUrl is required.

Required inputs

imageUrlstring
Public HTTP(S) URL, fileUrl returned by upload_files, or Base64 Data URI (PNG, JPEG, or WebP; max 128 KB) of a source image with one clearly visible subject or object.

Edit the sample inputs for your own task before submitting.

Image to 3D Model 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/ai-image-to-3d-model/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"imageUrl":"https://vidmage.ai/assets/images/ai-tools/ai-3d-model-detail-2.webp"}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }
Parameters and input rules1 field
FieldTypeRequiredDefaultMeaning and limits
imageUrlstringYesNot specifiedPublic HTTP(S) URL, fileUrl returned by upload_files, or Base64 Data URI (PNG, JPEG, or WebP; max 128 KB) of a source image with one clearly visible subject or object. No additional field constraint listed.

Retrieve the result

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

POST /api/v1/ai-image-to-3d-model/query

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

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

Four-View Image to 3D Model

POST /api/v1/ai-four-view-to-3d-model/submit

Full API documentation ↗

imageUrl is required.

Required inputs

imageUrlstring
Public HTTP(S) URL, fileUrl returned by upload_files, or Base64 Data URI (PNG, JPEG, or WebP; max 128 KB) for one 2×2 composite image containing four consistent views of the same subject or object.

Edit the sample inputs for your own task before submitting.

Four-View Image to 3D Model 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/ai-four-view-to-3d-model/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"imageUrl":"https://vidmage.ai/assets/images/ai-tools/ai-3d-model-detail-2.webp"}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }
Parameters and input rules1 field
FieldTypeRequiredDefaultMeaning and limits
imageUrlstringYesNot specifiedPublic HTTP(S) URL, fileUrl returned by upload_files, or Base64 Data URI (PNG, JPEG, or WebP; max 128 KB) for one 2×2 composite image containing four consistent views of the same subject or object. No additional field constraint listed.

Retrieve the result

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

POST /api/v1/ai-four-view-to-3d-model/query

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

Task states and recovery ↗
Four-View Image to 3D Model query
curl -X POST "https://vidmage.ai/api/v1/ai-four-view-to-3d-model/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "modelUrl": "https://..." } }

Text to 3D Model

POST /api/v1/ai-text-to-3d-model/submit

Full API documentation ↗

prompt is required.

Required inputs

promptstring
Text description of the 3D model (min 5 chars).

Edit the sample inputs for your own task before submitting.

Text to 3D Model 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/ai-text-to-3d-model/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A stylized low-poly camping lantern with a metal handle, glass chamber, and production-ready proportions"}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }
Parameters and input rules1 field
FieldTypeRequiredDefaultMeaning and limits
promptstringYesNot specifiedText description of the 3D model (min 5 chars). Minimum length: 5

Retrieve the result

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

POST /api/v1/ai-text-to-3d-model/query

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

Task states and recovery ↗
Text to 3D Model query
curl -X POST "https://vidmage.ai/api/v1/ai-text-to-3d-model/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "modelUrl": "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 3D Model3d API1 generation request: 200 credits
How this is calculated
  • Per request: 200 credits / request

A fixed credit charge applies to this API request.

Estimate your own request ↗
200 credits / requestSee calculation details
Four-View Image to 3D Model3d API1 generation request: 200 credits
How this is calculated
  • Per request: 200 credits / request

A fixed credit charge applies to this API request.

Estimate your own request ↗
200 credits / requestSee calculation details
Text to 3D Model3d API1 generation request: 200 credits
How this is calculated
  • Per request: 200 credits / request

A fixed credit charge applies to this API request.

Estimate your own request ↗
200 credits / requestSee 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 3D Generation API

VidMage's AI 3D Generation API is an interface for generating 3D assets from text or image inputs. Separate endpoints accept a text prompt, a reference image, or a combined four-view image sheet. The output is a 3D model for viewing, concept review, or later stages of a 3D workflow. To try this API in your browser, open the API Playground.

AI 3D Generation API capabilities

Text-to-3D generation
Describe an object in a text prompt when your application starts with a written asset brief.
Image-to-3D generation
Supply a reference image to request a generated model guided by the object shown in that image.
Four-view generation
Provide one combined image containing four consistent views of the same object in a two-by-two grid.

What you can build

Game prop concepts in 3D

Turn a written prop brief, such as a weathered treasure chest, into a model for early art review. A viewer exposes the form from different angles before artists move on to topology, texturing, and preparation for the game engine.

Product sketches as 3D previews

A lamp or chair concept can be easier to discuss when the team can rotate it. Generate a 3D asset from the concept image for that conversation, with detailed CAD and manufacturing specifications handled in later design work.

Draft assets from four views

Artists who already have front, back, and side references can combine four consistent views in one two-by-two image sheet. Use it to guide a model draft, comparing the resulting proportions with the source views during further modeling.

How to use AI 3D Generation 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 modelUrl from the completed task. Preview the result in your app and save a copy to your own storage for later use.

Input tips
Prepare one four-view sheet
Combine four views of the same object into one two-by-two image and send it as imageUrl. This route does not accept four separate image URLs.
Check downstream model requirements
Retrieve the asset through modelUrl and inspect it in your viewer. The contract has no rigging, polygon-count, or output-format controls and does not establish watertight geometry. Check the asset against your game or print workflow and plan any conversion or cleanup.

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/ai-image-to-3d-model/query
Completed result
modelUrl
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 ↗

Explore more APIs on VidMage

  • AI Text to Image API for Prompted Visuals↗
  • Nano Banana API↗
  • Qwen Image API↗
  • GPT Image API↗
  • Seedream API↗
  • AI Image Upscaler API for 2x and 4x Requests↗
  • AI Image to Image API for Prompted Edits↗
  • Midjourney Image API↗