DrawThings gRPC Image Generation Example

Note: Some advanced CLI options (such as upscaling) are only available when running the main CLI directly:

uv run python src/drawthings_grpc_sample/generate.py [args]

The root-level wrapper (generate.py) does not support new options like --upscale, --upscale-model, or --upscale-factor. Always use the direct path for these features.

Simple Python example demonstrating how to call the DrawThings gRPC API.

See Also: DrawThings gRPC Protocol

Setup

# Install uv if you don't have it already 
curl -LsSf https://astral.sh/uv/install.sh | sh

# Set up the UV Python environment 
uv sync

Dependencies are already configured in pyproject.toml.

defaults.yaml

Runtime defaults are centralized in defaults.yaml at the repository root.

• grpc: server, port, compression, request_chunked, tls, tls_ca_file
• generation.t2i: t2i-specific defaults
• generation.i2i: i2i-specific defaults

Set sampler as a sampler name string in YAML (for example, "UniPC"), not just an index.

Set grpc.request_chunked to control the request flag that appears in server logs as "should send in chunks?".

Both CLIs load this file automatically:

• uv run python generate.py
• uv run python model_list.py

You can also point to a different defaults file via DRAWTHINGS_DEFAULTS_FILE=/path/to/defaults.yaml.

Run

Make sure the DrawThings gRPC server is running first:

1. ✅ Server Online
2. ✅ gRPC (not HTTP)
3. ✅ Enable Model Browsing
4. ✅ Know whether server TLS is ON or OFF

Then generate an image (TLS ON by default):

# Full CLI (all options, including upscaling):
uv run python src/drawthings_grpc_sample/generate.py t2i --prompt "a cat" --steps 20 --seed 42 --upscale

# Compatibility wrapper (basic options only):
uv run python generate.py --prompt "a cat" --steps 20 --seed 42

If server TLS is OFF, disable TLS explicitly with --no-tls:

# Full CLI (all options, including upscaling):
uv run python src/drawthings_grpc_sample/generate.py t2i --no-tls --upscale

# Compatibility wrapper (basic options only):
uv run python generate.py --no-tls

Options (full CLI)

--upscale                Enable upscaling (flag or --upscale true)
--upscale-model <file>   Upscale model filename (.ckpt)
--upscale-factor <int>   Upscale factor (e.g., 2)
--server localhost   gRPC server address
--port 7859          gRPC server port
--model <file>       Model filename on server
--prompt <text>      Text prompt
--negative <text>    Negative prompt
--width 512          Image width (rounded to 64px)
--height 512         Image height (rounded to 64px)
--seed <int>         Random seed
--steps 20           Inference steps
--cfg 7.0            CFG scale
--sampler <value>    Sampler name or index
--chunked            Request chunked image responses
--no-chunked         Request non-chunked image responses
--tls                Use TLS (default)
--no-tls             Disable TLS and use plaintext
--tls-ca-file <path> Path to PEM CA certificate used to verify TLS server certificate

TLS And Certificate Verification

• The client now includes the Draw Things root CA used by the server, so standard Draw Things TLS works without extra setup.
• TLS is ON by default.
• If server TLS is OFF, use --no-tls.
• If your server uses a different/private CA, pass --tls-ca-file /path/to/ca.pem.

If you see CERTIFICATE_VERIFY_FAILED, the client does not trust the presented certificate chain. Use --tls-ca-file with the correct CA PEM.

TLS/Plaintext Test Matrix

To verify all four commands pass, run them in two phases:

1. With server TLS ON:
   • python model_list.py
   • python generate.py
2. With server TLS OFF:
   • python model_list.py --no-tls
   • python generate.py --no-tls

Output

Images are saved to the img/ directory with timestamp filenames:

• img/generated_20260409_143052_0.png

---

View Available Models

uv run drawthings-grpc-model-list

# compatibility wrapper still works
uv run python model_list.py

# plaintext mode
uv run drawthings-grpc-model-list --no-tls
uv run python model_list.py --no-tls

The model list output also includes available samplers.

---

Sources

• draw-things-comfyui - Official Draw Things extension for ComfyUI (TypeScript frontend, Python backend)
• draw-things-community - Community repository with Swift diffusion model implementations and self-hosted gRPC server