Idol Image To 3d API Documentation

Idol Image To 3d API Documentation

Playground

Try it on WaveSpeedAI!

Idol Image-to-3D is an open-source model that turns a single photo, render, or generated image into a complete 3D Gaussian Splat, reconstructing views beyond the visible input for interactive 3D objects, visualization, and asset creation workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Idol Image-to-3D generates a 3D Gaussian Splatting representation from a single image. Upload a clear image of an object, configure the Gaussian count and background handling, then retrieve the result as a .ply splat file.


Why Choose This?

  • Single-image 3D generation — Create a Gaussian splat representation from one reference image.
  • Gaussian Splatting output — Export the generated result as a .ply file.
  • Automatic background removal — Remove the source background before generation when needed.
  • Density control — Adjust the number of Gaussians to balance representation density and file size.
  • Seed control — Use a fixed seed when comparing generation settings.

Parameters

ParameterRequiredDescription
imageYesInput image URL, data URI, or Base64 image. A clear image with one main object is recommended.
num_gaussiansNoNumber of Gaussians in the generated splat, from 32768 to 1048576. Default: 262144. Higher values produce a denser representation and a larger output file.
remove_backgroundNoRemove the image background before generation. Default: true.
seedNoRandom seed. Use -1 for random generation.

How to Use

  1. Upload an image — Provide a clear image containing the object you want to reconstruct.
  2. Configure density optional — Adjust num_gaussians based on the desired representation density and file size.
  3. Configure background removal optional — Keep remove_background=true when the source background should be removed.
  4. Set a seed optional — Use a fixed seed when comparing generation settings.
  5. Submit — Generate and retrieve the .ply splat file.

Pricing

$0.05 per generation.

The number of Gaussians, background-removal setting, and seed do not add separate charges.


Best Use Cases

  • Object visualization — Create a Gaussian splat representation from a product or object image.
  • 3D previews — Generate orbitable assets for compatible 3D viewers.
  • Creative assets — Convert renders, illustrations, or AI-generated object images into splat-based 3D representations.
  • Rapid 3D prototyping — Create a 3D representation from a single visual reference.

Pro Tips

  • Use one main object with minimal obstruction.
  • Keep the full object visible within the frame.
  • A simple or transparent background can make object separation easier.
  • Increase num_gaussians when a denser representation is needed.
  • Use lower Gaussian counts when smaller output files are preferred.
  • Thin structures and fine surface details may be more difficult to reconstruct from a single view.

Output

Each request returns a 3D Gaussian Splatting .ply file for use with compatible Gaussian-splat viewers and workflows.


Notes

  • The model reconstructs the object from a single input view, so geometry not visible in the source image is inferred.
  • remove_background defaults to true.
  • num_gaussians supports values from 32768 to 1048576.
  • The output is a Gaussian Splatting .ply, not a conventional polygon mesh.
  • Idol is an open-weights image-to-3D model developed by Speri Labs and released under the Apache 2.0 license.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "num_gaussians": 262144,
  "remove_background": true
}
JSON
)

# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 60 \
  -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/idol/image-to-3d" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"); then
  printf 'Submit failed. %s\n' "${CHECK}" >&2
  exit 1
fi

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id. %s\n' "${CHECK}" >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
  # Transient errors (429, 5xx) are retried, honoring Retry-After.
  HTTP_CODE=$(curl --silent --show-error --fail-with-body \
    --connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
    --output "${BODY_FILE}" --write-out '%{http_code}' \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
  case "${HTTP_CODE}" in
    2??) ;;
    000|429|5??)  # dropped connection or temporary error: keep polling
      printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      sleep 10; continue ;;
    *) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      cat "${BODY_FILE}" >&2; exit 1 ;;
  esac
  RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted)
      printf 'Task %s ended with status %s\n' "${PREDICTION_ID}" "${STATUS}" >&2
      printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Retry temporary errors only while polling, never the submit request. Errors, retries and timeouts

Parameters

Task Submission Parameters

Request Parameters

ParameterTypeRequiredDefaultRangeDescription
imagestringYes1 ~ unlimited charactersSingle input image URL, data URI or base64 image. Works best with one clear object.
num_gaussiansintegerNo26214432768 ~ 1048576Number of 3D Gaussians in the splat. Higher values make a denser, larger file; they do not add new detail.
remove_backgroundbooleanNotrue-Remove the image background before generation. Disable to use existing image alpha.
seedintegerNo--Random seed. Use -1 for a random seed.

Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.

Response Parameters

ParameterTypeDescription
codeintegerHTTP status code (e.g., 200 for success)
messagestringStatus message (e.g., “success”)
data.idstringUnique identifier for the prediction, Task Id
data.modelstringModel ID used for the prediction
data.outputsarrayOutput values, usually URL strings; some models return text strings or structured result objects (empty when status is not completed)
data.urlsobjectObject containing related API endpoints
data.statusstringTask status. completed is successful; failed, cancelled, timeout, and deleted are failure terminal statuses.
data.created_atstringISO timestamp of when the request was created (e.g., “2023-04-01T12:34:56.789Z”)
data.errorstringError message (empty if no error occurred)
data.timingsobjectObject containing timing details
data.timings.inferenceintegerInference time in milliseconds

Result Request Parameters

ParameterTypeRequiredDefaultDescription
idstringYes-Task ID

Result Response Parameters

ParameterTypeDescription
codeintegerHTTP status code (e.g., 200 for success)
messagestringStatus message (e.g., “success”)
dataobjectThe prediction data object containing all details
data.idstringUnique identifier for the prediction
data.modelstringModel ID used for the prediction
data.outputsarray<string | object>Array of generated outputs (empty when status is not completed). Items are usually URL strings, but may be text strings or structured result objects, depending on the model.
data.urlsobjectObject containing related API endpoints
data.statusstringStatus: completed is successful; failed, cancelled, timeout, and deleted are failure terminal statuses
data.created_atstringISO timestamp of when the request was created
data.errorstringError message (empty if no error occurred)
data.timingsobjectObject containing timing details
data.timings.inferenceintegerInference time in milliseconds
© 2026 WaveSpeedAI. All rights reserved.