Z-Image-Turbo on Jetson — Deployment Guide

View source on GitHub
Preset

Deploy Image Generation Service

Deploy Z-Image-Turbo as an HTTP API on your Jetson Orin NX for local text-to-image and img2img generation.

DevicePurpose
NVIDIA Jetson Orin NX (16GB)Runs the Z-Image-Turbo model

What you'll get:

  • One-click deployment — remote via SSH or directly on the Jetson
  • HTTP API at port 8000 for text-to-image and img2img
  • Fully offline — no cloud dependency

Requirements: Jetson Orin NX 16GB with JetPack 6, NVIDIA Docker runtime, internet access (models are downloaded automatically on first deploy).

1

Deploy Image Generation Service

Deploy the Z-Image-Turbo API container to your Jetson.

Deployment method

Deploy to your Jetson Orin NX over SSH with one click.

Wiring
  1. Ensure Jetson is on the same network and SSH is enabled
  2. Fill in Jetson IP, SSH credentials, model root path, and output directory
  3. Click Deploy — model weights and TRT engines for the chosen resolution are downloaded automatically on first run
What you will be asked for(filled in the SenseCraft Solution app)
  • Host / IP*
  • SSH Username*default nvidia
  • SSH Password*
  • Model Root*default /home/nvidia/models

    Directory containing model weights and TRT engines (see requirements)

2 more with defaults you can keep
  • Resolutiondefault 512
    2 options
    • · 384x384 (~73s)
    • · 512x512 (~100s)
  • Output Directorydefault /home/nvidia/z-image-output

    Generated images are saved here

Troubleshooting
IssueSolution
SSH connection failedVerify IP, username, password, and that SSH service is running on Jetson
Docker not foundInstall Docker and NVIDIA Container Toolkit on Jetson
HuggingFace download failsThe script auto-falls back to hf-mirror.com; if both are blocked, configure a proxy on the Jetson or place the model files in the model root path manually
Download interruptedRe-run deploy — partial files (.part) are discarded and only missing files are re-fetched
API not respondingCheck container logs: docker logs z-image-api
Docker permission deniedRun sudo usermod -aG docker <user> and re-login
After Deployment
  1. The Z-Image-Turbo API is running on your Jetson at port 8000
  2. Health check available at http://<jetson-ip>:8000/health
  3. Generated images are saved to the output directory
2

Generate Images

Type a prompt to generate an image. Each generation takes 1-2 minutes. The generated image appears directly in the verification panel.

Troubleshooting
IssueSolution
Health check failsVerify the Jetson is reachable and port 8000 is not blocked by firewall
Generate returns errorCheck container logs: docker logs z-image-api
Request timeoutGeneration takes 1-2 minutes. Increase HTTP client timeout to 180s
After Deployment

Z-Image-Turbo has been deployed successfully on your Jetson.

API Reference

Health Check
curl http://<jetson-ip>:8000/health
Text-to-Image
curl -X POST http://<jetson-ip>:8000/generate_json -H 'Content-Type: application/json' -d '{"prompt": "A cute cat, photorealistic", "num_steps": 4}'
Image-to-Image
curl -X POST http://<jetson-ip>:8000/generate -F 'prompt=A cat wearing a red scarf' -F 'image=@/path/to/reference.png' -F 'num_steps=8' -F 'strength=0.65'

Validation Checklist

  1. Health endpoint returns {"success": true}
  2. Text-to-image generation returns image URL in response
  3. Generated PNG files appear in the output directory