# 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](/docs/API.zh-CN.md), a [ready-to-run Python client](/docs/img3d_client.py), and a [machine-readable OpenAPI schema](/api/openapi.json). 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`:

```bash
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:

```bash
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:

```bash
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.

```bash
#!/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](https://github.com/TencentARC/Pixal3D). Visibility rasterization: [NVIDIA nvdiffrast](https://nvlabs.github.io/nvdiffrast/). Upstream and dependency licenses continue to apply. Service-specific API features above are WarmPix additions, not features claimed for Tencent's public demo.
