◈ WarmPix3D STUDIO
中文Open studio ↗
THE DEVELOPER NOTEBOOK / V2.1

API field guide✳

One image. One request. Bring image-to-3D into your application.

WarmPix Image-to-3D API

Overview

Base URL: https://img3d.warmpix.com
API version: 2.1.0
Engine: the deployed single-image Pixal3D pipeline
Output: a downloadable GLB 2.0 textured mesh, not an automatically rigged character.

This guide describes the WarmPix service wrapper, not an upstream Tencent-hosted API. Endpoint names, authentication, queue behavior and defaults below come from this deployment's server.py and api_contract.py.

The complete flow is create session → upload image → poll job → download GLB. Generation is asynchronous. A successful upload returns a job, not the model. Only state: "complete" means the GLB is ready.

The site offers a Chinese guide, a ready-to-run Python client, and a machine-readable OpenAPI schema. Use HTTPS directly; do not submit files to the HTTP redirect endpoint.

1. Session authentication

There is currently no API key, Bearer token, OAuth login, or public gallery. The API creates a private anonymous session:

Item How to obtain it Where to send it
wp3d_session cookie Set-Cookie from GET /api/session All private job and file requests
CSRF token JSON csrf from GET /api/session X-CSRF-Token on POST and DELETE

Use a persistent cookie jar or one HTTP client session. Do not copy only the CSRF token: it is bound to the corresponding cookie. The cookie is Secure, HttpOnly and SameSite=Strict. Calling /api/session with the same valid cookie renews that session's seven-day browser lifetime.

Keep your cookie file private, outside source control. Clearing it, changing clients without transferring your own session, or allowing the cookie to expire can make old jobs inaccessible. The API cannot restore an anonymous session from a job ID. A separately opened browser does not automatically share the Python/cURL client's jobs.

Command-line and server-to-server clients do not need an Origin header. When supplied, it must be https://img3d.warmpix.com. Cross-origin browser applications are not enabled by a permissive CORS policy; integrate through your backend or the same origin. Never disable TLS certificate verification.

2. Python quick start

Requires Python 3.10+ and requests:

python3 -m pip install requests
curl --fail --show-error \
  https://img3d.warmpix.com/docs/img3d_client.py \
  -o img3d_client.py

python3 img3d_client.py ./object.png \
  --output ./object.glb \
  --session-file ./.warmpix-img3d.cookies \
  --resolution 1024 \
  --texture 4096 \
  --quality detail \
  --seed 42

The client obtains the cookie and CSRF token, waits for a ready worker, submits the image with an idempotency key, polls real job stages, and streams the completed GLB into a temporary file. It checks the GLB header, declared length, and server-recorded byte count before publishing the final file, then prints its SHA-256 checksum. Existing output files are not overwritten unless --overwrite is explicitly supplied; a failed download leaves the existing file intact.

Export metadata is optional. If it is missing or unavailable after a verified model download, the client prints a warning and still exits successfully. A --record result then contains export: null and metadata_error; generation or model-download failures still fail the command.

To enable source-color reprojection on visible surfaces:

python3 img3d_client.py ./object.png \
  --output ./object-reference.glb \
  --preserve-reference \
  --record ./generation-result.json

The optional record contains job settings, timing, output checksum and export metadata—not cookies or CSRF tokens. Keep it private if job identifiers themselves are sensitive.

To resume polling/downloading after closing the terminal, retain the cookie file and use the previously printed job ID:

python3 img3d_client.py \
  --job-id YOUR_JOB_ID \
  --session-file ./.warmpix-img3d.cookies \
  --output ./object.glb \
  --timeout 3600

--timeout is the client's queue-plus-polling deadline, not a server cancellation. A timed-out client must not assume the GPU job stopped. Use --job-id to resume. An explicit --retry-failed with --job-id retries only a failed job using its retained input and settings.

3. Complete cURL example

Requires Bash, cURL and jq. Set IMAGE to your local PNG, JPEG or WEBP file. This creates one job and polls for up to 30 minutes; increase the polling deadline for a long queue.

#!/usr/bin/env bash
set -euo pipefail
umask 077

BASE='https://img3d.warmpix.com'
IMAGE='./object.png'
COOKIE='./.warmpix-img3d.cookies'
OUT='./object.glb'

# Keep this cookie jar: it owns the submitted job.
SESSION=$(curl --fail-with-body --silent --show-error \
  --cookie "$COOKIE" --cookie-jar "$COOKIE" \
  "$BASE/api/session")
CSRF=$(printf '%s' "$SESSION" | jq -er '.csrf')

HEALTH=$(curl --fail-with-body --silent --show-error "$BASE/api/health")
printf '%s' "$HEALTH" | jq -e '.ready == true' >/dev/null || {
  echo 'Engine is not ready. Check /api/health and try later.' >&2
  exit 1
}

# Reuse this exact key, cookie and payload if submission's outcome is uncertain.
KEY=$(python3 -c 'import uuid; print(uuid.uuid4())')
printf 'Idempotency-Key: %s\n' "$KEY"
JOB=$(curl --fail-with-body --silent --show-error \
  --connect-timeout 20 --max-time 300 \
  --cookie "$COOKIE" \
  --header "X-CSRF-Token: $CSRF" \
  --header "Idempotency-Key: $KEY" \
  --form "image=@${IMAGE}" \
  --form 'seed=42' \
  --form 'resolution=1024' \
  --form 'texture=4096' \
  --form 'texture_quality=detail' \
  --form 'preserve_reference=false' \
  "$BASE/api/jobs")
JOB_ID=$(printf '%s' "$JOB" | jq -er '.id')
printf 'Job ID: %s\n' "$JOB_ID"

DEADLINE=$((SECONDS + 1800))
while true; do
  JOB=$(curl --fail-with-body --silent --show-error \
    --cookie "$COOKIE" "$BASE/api/jobs/$JOB_ID")
  STATE=$(printf '%s' "$JOB" | jq -r '.state')
  printf '%s\n' "$JOB" | jq '{id,state,stage,ahead,error}'
  case "$STATE" in
    complete) break ;;
    failed) echo 'Generation failed; inspect .error before retrying.' >&2; exit 1 ;;
  esac
  if (( SECONDS >= DEADLINE )); then
    echo "Polling stopped; job $JOB_ID may still be running. Keep the cookie jar." >&2
    exit 1
  fi
  sleep 3
 done

if [[ -e "$OUT" ]]; then
  echo "Refusing to overwrite $OUT" >&2
  exit 1
fi
# Keep incomplete downloads separate from the final model.
curl --fail --silent --show-error \
  --connect-timeout 20 --max-time 600 \
  --cookie "$COOKIE" \
  "$BASE/api/jobs/$JOB_ID/model" --output "$OUT.part"
python3 - "$OUT.part" <<'PY'
import os, struct, sys
with open(sys.argv[1], 'rb') as f:
    magic, version, length = struct.unpack('<4sII', f.read(12))
assert magic == b'glTF' and version == 2
assert length == os.path.getsize(sys.argv[1]), 'Truncated GLB'
PY
mv "$OUT.part" "$OUT"

curl --fail-with-body --silent --show-error \
  --cookie "$COOKIE" "$BASE/api/jobs/$JOB_ID/metadata" | jq .

Do not set multipart Content-Type yourself: cURL or your HTTP library must generate the boundary. Do not send a JSON body or base64 image; this endpoint takes a multipart file.

4. Generation parameters

POST /api/jobs accepts multipart/form-data:

Field Type Default Accepted values and behavior
image File Required One PNG, JPEG or WEBP image; not a URL or a list
seed Integer 42 0 through 2147483647
resolution Integer 1024 1024 or 1536; geometry cascade resolution
texture Integer 4096 1024, 2048, 4096; output texture atlas dimension
texture_quality String detail standard: 12 texture steps; detail: 24 texture steps and a mild color-only clarity filter
preserve_reference Boolean false Opt-in visible-surface source-color projection; send true or false

Practical starting points: use 1024 / 2048 / standard for a smaller, lighter result; 1024 / 4096 / detail for the current default; and 1536 / 4096 / detail to request higher geometry detail. Larger settings can cost more time and memory; they are not a guarantee of better reconstruction for every image.

preserve_reference=true retains the high-resolution aligned source crop, projects its colors onto confidently camera-visible, sufficiently front-facing texels, and leaves other surfaces on their generated texture. It uses depth visibility, source alpha filtering and a silhouette-overlap gate. If alignment is insufficient, projection is skipped and the generated texture is retained; inspect /metadata for reference_reprojection.applied and skip_reason.

This option is not a face detector, a face-specific UV unwrap, relighting, generative super-resolution, or an automatic rigging pass. It can carry photographed shadows or highlights into the base-color texture, and local details can still be misaligned even when the silhouette matches. It is intentionally off by default. Alpha and metallic/roughness maps are not projected or sharpened.

All new outputs embed lossless PNG textures. Old completed files are not rewritten and may contain WebP textures. The same seed helps repeat a configuration but does not promise bit-identical results across software/hardware changes.

5. Endpoint reference

All paths are relative to the base URL. “Cookie + CSRF” means both the session cookie and X-CSRF-Token header.

Method and path Authentication Success Purpose
GET /api/session None; existing cookie optional 200 Create or renew the private session; return CSRF token
GET /api/health None 200 Live readiness, queue size, supported settings and API version
GET /api/openapi.json None 200 OpenAPI schema; import into API tooling
POST /api/jobs Cookie + CSRF 202, or 200 replay Upload and queue one generation
GET /api/jobs?limit=20&cursor=... Cookie 200 List this session's jobs, newest first
GET /api/jobs/{id} Cookie 200 Read job state, stage, settings and result statistics
POST /api/jobs/{id}/retry Cookie + CSRF 202 Requeue a failed job with its existing input/settings
GET /api/jobs/{id}/image Cookie 200 binary Normalized private PNG input, not original file metadata
GET /api/jobs/{id}/thumbnail Cookie 200 binary Private WEBP thumbnail; older jobs may fall back to PNG
GET /api/jobs/{id}/model Cookie 200 binary Completed GLB, model/gltf-binary
GET /api/jobs/{id}/metadata Cookie 200 Export encoding, texture size, checksums and projection result
DELETE /api/jobs/{id} Cookie + CSRF 200 Delete a queued, failed or completed job and its files

A running job cannot be deleted or cancelled through this API: deletion returns 409 job_running. Deleting a queued job removes it before the worker claims it. Deletion is irreversible and also removes that job's idempotency mapping.

Listing returns { "jobs": [...], "next_cursor": "..." }. limit defaults to 20 and accepts 1–100. Pass the returned next_cursor unchanged on the next request; stop when it is null. The cursor belongs to this session. If its pivot job was deleted or expired, restart pagination rather than guessing a cursor. Store job IDs returned by creation; jobs outside the newest list page are still addressable directly while retained.

6. Job states, stages and timing

Field Meaning
state queued, running, complete, or failed
stage Current actual operation, not a fabricated percentage
ahead Jobs ahead of this attempt in the global queue; present when queued
created, updated Unix timestamps in seconds
attempt_started Queue-entry time for the current attempt; creation time for the first attempt
attempts Starts at 1; increments on explicit retry
duration Server processing time for the latest attempt; excludes queue and file transfer
vertices, faces, bytes Populated on successful export
texture_encoding Output encoding when export metadata is available; may be null for historical jobs
error Stable failure code, or null

Typical stages are queued → preprocessing → camera → generating → exporting → uv_unwrap → baking → reprojecting → complete. The reprojection stage is optional. A checkpointed retry may skip earlier generation stages and resume export. Poll state, not an assumed stage order; future minor versions may introduce more stage labels.

GET /api/jobs/{id} supplies Retry-After: 3 for active jobs. Polling every three seconds is adequate. A 200 health response alone does not mean the model worker is ready: check the boolean ready. ready or busy worker status can accept jobs. loading or starting means initialization is in progress; waiting_gpu means available GPU memory is insufficient; recovering, failed or stopped means generation is unavailable. offline means the worker is missing, its heartbeat is stale or invalid, or its process is no longer alive. Unavailable-worker submission/retry responses retain 503 engine_starting for compatibility and include Retry-After: 10.

Newly exported models include optional metadata.stage_seconds in GET /api/jobs/{id}/metadata. It reports measured server seconds per completed processing stage, excluding queue and download time. Historical models may omit it. Upload decoding and storage are bounded separately from health/status requests so large images do not block polling.

7. Duplicate-safe submissions and retries

For POST /api/jobs, send a client-generated Idempotency-Key of 8–128 characters using letters, digits, ., _, :, or -. A UUID is a convenient choice. The key is scoped to the private session.

First submission returns 202 plus a Location header pointing to the job. Repeating the same cookie, key, identical original image bytes, and equivalent settings returns the existing job with 200 and Idempotency-Replayed: true; it does not run another generation. The replay still works while the worker is temporarily unavailable. Reusing a key with different image bytes or settings returns 409 idempotency_conflict.

Keep the key when an upload times out or a proxy returns 502/504: the server might already have accepted the job. Use the same key to recover the original job instead of submitting a new one. A new key intentionally creates a new job. Keys are retained with jobs, not permanently: deleting or expiring a job removes its replay protection.

Idempotent submission is different from retrying failed inference. POST /api/jobs/{id}/retry accepts only state: failed, keeps the same job ID/input/settings, clears old error/output statistics, increases attempts, and puts the new attempt at the queue tail. A saved export checkpoint can avoid repeating successful geometry generation. A completed model cannot be retried; create a new job to regenerate or change settings. Do not blindly replay the retry endpoint after a connection loss—poll the job first.

8. Errors and operational limits

Most API errors are JSON { "detail": "error_code" }. FastAPI multipart/type validation can instead return a list of structured errors. Proxy-level errors, such as a request rejected by Nginx before reaching Python, can be HTML rather than JSON.

HTTP status Representative codes Action
400 invalid_host, invalid_idempotency_key Use the correct hostname and key format
401 session_required Obtain a session; retain the matching cookie
403 csrf_invalid, origin_invalid Refresh CSRF with the same cookie; fix Origin
404 job_not_found, cursor_not_found Check cookie ownership/ID; job may have expired or been deleted
409 model_not_ready, job_running, retry_unavailable, idempotency_conflict Check job state or payload; do not blindly resubmit
410 expired, metadata_unavailable Expected retained file/metadata is unavailable
413 image_too_large Reduce upload size
422 invalid_image, invalid_settings, or validation list Fix image or multipart fields
503 engine_starting, storage_low Check health; wait or have the operator resolve capacity
502, 504 Upstream/proxy unavailable Retry reads with backoff; recover uploads with the same idempotency key

A failed GPU job is normally reported by GET /api/jobs/{id} with HTTP 200, state: "failed" and its error; this is not an HTTP transport failure. Examples include gpu_memory, worker_restarted, generation_timeout, mesh_export_failed, or generation_failed. Treat unfamiliar error codes as failures and retain the job ID for diagnosis.

Images are limited to 20 MiB (20 × 1024 × 1024 bytes), at least 64 pixels on the shorter side, and at most 20 million decoded pixels. The saved normalized image is at most 4096 pixels on its longest side. The public proxy has an additional 22 MiB total-request limit, including multipart overhead. Only single-image upload is currently exposed; upstream multi-view code is not a multi-view API endpoint here.

There is currently no per-hour or per-session submission count cap and no configured global queue-count cap. This is not unlimited compute: one GPU worker processes jobs serially, GPU availability can change, and low disk space blocks new work. Schedule batch requests responsibly rather than flooding the queue.

Completed and failed jobs are eligible for cleanup seven days after their latest completion or failure; the worker checks periodically, so this is not an exact deletion-time guarantee. Queued/running jobs are not removed. A retry keeps the original creation timestamp but starts a fresh retention period when that attempt finishes. Cleanup and retry are coordinated so an accepted retry cannot lose its input to an overlapping cleanup pass. The worker has a 30-minute application timeout per attempt; deeply stuck native kernels can still require operator recovery. Keep your downloaded model locally.

9. Integration checklist

Keep one session per intended private workspace. Persist its cookie securely, and keep CSRF separate from job IDs. Upload with an idempotency key. Record the returned job ID immediately. Poll until complete or failed. Download only after completion, verify the GLB and retain it locally. Inspect export metadata before claiming source reprojection or a particular encoding was actually applied. Never expose another user's cookie, input, output URL with credentials, server logs, or private data directory.

For character workflows, inspect eyes, hair, hands, the unseen back, topology and material behavior in your target engine. This API produces a generated textured mesh; it does not promise perfect likeness, clean animation topology, an armature, skin weights, or commercial clearance for the depicted content.

10. Implementation sources

The deployed API behavior is defined in this project's server.py, api_contract.py, worker.py, reference_projection.py, and texture_settings.py. The OpenAPI schema is generated from the live server routes.

Upstream generation source: TencentARC/Pixal3D. Visibility rasterization: NVIDIA nvdiffrast. Upstream and dependency licenses continue to apply. Service-specific API features above are WarmPix additions, not features claimed for Tencent's public demo.