Inference With the Boltz-2 NIM | NVIDIA BioNeMo NIM Documentation

This documentation provides a comprehensive guide for using the Boltz-2 NIM for protein structure prediction and related tasks.

Before You Start

Deploy and start the Boltz-2 NIM container before using the API. For prerequisites, NGC authentication, docker run, and readiness checks, refer to Getting Started.

NIM API Reference

This documentation contains the API reference for the Boltz-2 NIM.

OpenAPI Specification

You can download the complete OpenAPI Specification for the Boltz-2 NIM here.

Example Notebooks

Example notebooks that show how to use the Boltz-2 NIM API:

Protein-Ligand Covalent Complex Visualization with Mol*Star - Use Boltz-2 NIM to predict and visualize a protein-ligand covalent complex structure using Mol*Star viewer

Protein-Ligand Covalent Complex View
Download boltz2_nim_protein_ligand_covalent_complex_molstar_visualization.ipynb
DNA-Protein Complex Visualization with py3Dmol - Use Boltz-2 NIM to predict and visualize a DNA-Protein complex structure using py3Dmol viewer

DNA-Protein Complex View
Download boltz2_nim_DNA_Protein_Complex_example_py3Dmol.ipynb

These notebooks provide hands-on examples of:

Setting up the NIM environment
Making API calls to the NIM
Processing and visualizing the results
Working with different types of molecular structures
Using various visualization tools

Predict a Protein Structure

Endpoint path: /biology/mit/boltz2/predict

Request type: post

Input Parameters

polymers (list[Polymer]): Required. A list of polymers (DNA, RNA, or Protein). Minimum 1, maximum 12 polymers allowed. Each polymer contains:
- id (string): Optional. Unique identifier for the polymer chain. Must contain 1-4 alphanumeric characters. If omitted, the NIM assigns an ID automatically.
- molecule_type (string): Required. Type of molecule - “dna”, “rna”, or “protein”.
- sequence (string): Required. The sequence of the polymer. Must be 1-4,096 characters and contain only valid characters for the molecule type. For proteins, valid characters are standard one-letter amino acid codes plus X for ambiguous residues. For DNA, use A, T, C, and G. For RNA, use A, U, C, and G.
- cyclic (boolean): Optional (default: false). Whether the polymer forms a cyclic structure.
- msa (dictionary): Optional. Multiple Sequence Alignments for protein molecules only, with a maximum of three database entries. This nested dictionary contains a mapping of database names to alignment formats and records (for example {"database_1" : {"a3m" : {"format" : "a3m", "alignment" : ">1\nMVNIDIAIAMAI", "rank" : 0}}}). The alignment format key and the format field must use lowercase values from csv, fasta, a3m, or sto (case-sensitive). Only a3m and csv alignments are consumed during inference; fasta and sto are accepted by the schema but removed during input preparation. The first sequence in each alignment must match the polymer sequence. Each alignment record may include an optional rank field (default: -1).
- modifications (list[Modification]): Optional. Chemical modifications to specific residues in the sequence. Each modification contains:
  - ccd (string): Required. Chemical Component Dictionary (CCD) ID of the modification (1-5 uppercase alphanumeric characters).
  - position (int): Required. The 1-based index of the residue to modify.
- structural_templates (list[StructuralTemplate]): Optional. Up to four structural templates to guide prediction. Structural templates are supported for protein polymers only. Each template contains:
  - structure (string): Required. The structural template content in the specified format.
  - format (string): Optional (default: cif). The format of the template structure. Supported formats: cif or pdb.
  - name (string): Optional. Identifier or name for the template (for example, a PDB ID). Maximum 64 characters; only alphanumeric characters, underscores, and hyphens are supported.
  - chain_id (string): Optional. Chain ID from the template structure, containing 1-4 alphanumeric characters. If omitted, the NIM selects the best-matching chain based on sequence similarity.
ligands (list[Ligand]): Optional (default: empty list). A list of ligands. Maximum 20 ligands allowed. Each ligand contains:
- id (string): Optional. A chain ID for the ligand. If omitted, the NIM assigns IDs such as B1, B2, and so on.
- ccd (string): Optional. Chemical Component Dictionary (CCD) code for the ligand (1-5 uppercase alphanumeric characters). Must be uppercase.
- smiles (string): Optional. SMILES string representation of the ligand. Either CCD or SMILES must be provided, but not both.
- predict_affinity (boolean): Optional (default: false). Enable affinity prediction for this ligand. When enabled, the model predicts binding affinity between the protein and this ligand. Only one ligand per request can have predict_affinity=True. Duplicate CCD or SMILES values across ligands are not allowed when affinity prediction is enabled.
- output_affinity_embedding (boolean): Optional (default: false). When enabled together with predict_affinity on the same ligand, include 384-dimensional affinity embedding vectors under the ligand’s entry in the affinities response field.
constraints (list[Union[Pocket, Bond]]): Optional (default: empty list). Optional constraints for the prediction. Can be either:
- Bond Constraint: Specifies atomic bonds between molecules
  - constraint_type: “bond”
  - atoms (list[Atom]): List of exactly two atoms involved in the bond. Each atom contains:
    - id (string): Required. Chain identifier for the atom.
    - residue_index (int): Required. 1-based index of the residue containing the atom.
    - atom_name (string): Required. Name of the specific atom.
- Pocket Constraint: Defines binding site interactions
  - constraint_type: “pocket”
  - binder (string): Required. The ID of the binding ligand. Only one pocket binder is allowed per request.
  - contacts (list[Contact]): Required. List of contacts defining the pocket. Each contact contains:
    - id (string): Required. Chain identifier for the polymer contact residue.
    - residue_index (int): Required. 1-based index of the residue in the binding site.
recycling_steps (int): Optional (default: 3). The number of recycling steps to use for prediction. Range: 1-10.
sampling_steps (int): Optional (default: 50). The number of sampling steps to use for prediction. Range: 10-1,000.
diffusion_samples (int): Optional (default: 1). The number of diffusion samples to use for prediction. Range: 1-25.
max_parallel_samples (int): Optional. Maximum number of diffusion samples processed concurrently. Range: 1-25. Leave unset to use the optimized backend default. Lower values reduce peak GPU memory usage but increase runtime. For large complexes (sequence length ≥5000), start with 5 and reduce toward 1 if an out-of-memory error occurs.
step_scale (float): Optional (default: 1.638). Controls the magnitude of change applied at each diffusion sampling step. Larger values can speed up convergence but may reduce coordinate precision; smaller values can improve precision but require more sampling steps. Recommended range: 1.0-2.0. Range: 0.5-5.0.
without_potentials (boolean): Optional (default: false). Returns the results without potentials.
output_format (string): Optional (default: “mmcif”). The output format of the returned structure. Currently only “mmcif” is supported.
concatenate_msas (boolean): Optional (default: false). Concatenate Multiple Sequence Alignments for a polymer into one alignment.
sampling_steps_affinity (int): Optional (default: 200). The number of sampling steps to use for affinity prediction. Range: 10-1,000. Higher values may improve accuracy but increase runtime. Reduce for faster results.
diffusion_samples_affinity (int): Optional (default: 5). The number of diffusion samples to use for affinity prediction. Range: 1-10. Higher values may improve reliability but increase runtime. Reduce to 1 for faster results.
affinity_mw_correction (boolean): Optional (default: false). Enable molecular weight correction for affinity prediction, especially useful for metal-containing ligands.
write_full_pae (boolean): Optional (default: false). Write full Predicted Aligned Error (PAE) matrices as uncompressed .npz files under $NIM_OUTPUT_PATH/prediction_*/pae/ (pae_*_model_*.npz). Matrices are not included in the JSON response. Full matrices are float32 and scale as O(tokens²) per diffusion sample; on-disk size is close to the raw array size because these NPZ archives are not compressed.
write_full_pde (boolean): Optional (default: false). Write full Predicted Distance Error (PDE) matrices as uncompressed .npz files under $NIM_OUTPUT_PATH/prediction_*/pde/ (pde_*_model_*.npz). Matrices are not included in the JSON response. Full matrices are float32 and scale as O(tokens²) per diffusion sample; on-disk size is close to the raw array size because these NPZ archives are not compressed.

PAE and PDE values are expressed in ångströms (Å). Lower values generally indicate higher confidence in the predicted structure or pairwise relationships. Aggregate PDE scores (complex_pde_scores, complex_ipde_scores) are always returned in the JSON response. Full PAE/PDE matrices are written to $NIM_OUTPUT_PATH only when the corresponding request flags are enabled; the pae and pde JSON fields are deprecated and remain null. Aggregate PAE scores (such as complex_pae or complex_ipae in Boltz OSS confidence files) are not exposed as separate fields in the NIM JSON API. Mount $NIM_OUTPUT_PATH (default /opt/nim/output) when enabling these flags. Refer to Configuring the Boltz-2 NIM.

Outputs

structures (list[Structure]): The predicted protein structures. Each structure contains:
- structure (string): The contents of a single structural prediction in the specified format.
- format (string): The format of the structure record (currently “mmcif”).
- name (string): Optional name for the structure.
- source (string): Optional source file for the structure.
confidence_scores (list[float]): Confidence scores for each predicted structure.
ptm_scores (list[float]): Predicted TM score for the complete complex for each diffusion sample.
iptm_scores (list[float]): Predicted TM score aggregated at interfaces for each diffusion sample.
ligand_iptm_scores (list[float]): Interface TM score aggregated at protein-ligand interfaces for each diffusion sample.
protein_iptm_scores (list[float]): Interface TM score aggregated at protein-protein interfaces for each diffusion sample.
complex_plddt_scores (list[float]): Average pLDDT score for the complete complex for each diffusion sample.
complex_iplddt_scores (list[float]): Average pLDDT score with interface tokens upweighted for each diffusion sample.
complex_pde_scores (list[float]): Contact-weighted average PDE score for the complete complex, in ångströms. Always returned with one scalar per diffusion sample; no request flag is required. Lower values generally indicate higher confidence.
complex_ipde_scores (list[float]): Contact-weighted average PDE score aggregated at interfaces (ipDE), in ångströms. Always returned with one scalar per diffusion sample; no request flag is required. Lower values generally indicate higher confidence.
chains_ptm_scores (list[float]): Predicted TM score within each chain.
pair_chains_iptm_scores (list[dict[str, dict[str, float]]]): Predicted interface TM scores between each pair of chains. The response contains one dictionary keyed by chain ID.
pae (list[list[list[float]]] | null): Deprecated in the JSON response; always null. When write_full_pae is true, full PAE matrices are written as pae_*_model_*.npz under $NIM_OUTPUT_PATH/prediction_*/pae/.
pde (list[list[list[float]]] | null): Deprecated in the JSON response; always null. When write_full_pde is true, full PDE matrices are written as pde_*_model_*.npz under $NIM_OUTPUT_PATH/prediction_*/pde/.
affinities (dict[str, AffinityPrediction]): Always returned as an object. When no ligand has predict_affinity enabled, this object is empty. When affinity prediction is enabled, keys are ligand IDs and values contain:
- affinity_pic50 (list[float]): Predicted pIC50 binding affinity.
- affinity_pred_value (list[float]): Predicted log(IC50).
- affinity_probability_binary (list[float]): Binding probability in the range 0-1.
- model_1_affinity_pred_value (list[float]): Predicted log(IC50) from affinity ensemble model 1.
- model_1_affinity_probability_binary (list[float]): Binding probability from affinity ensemble model 1.
- model_2_affinity_pred_value (list[float]): Predicted log(IC50) from affinity ensemble model 2.
- model_2_affinity_probability_binary (list[float]): Binding probability from affinity ensemble model 2.
- affinity_embedding (list[list[float]] | null): Combined affinity embedding, with one 384-dimensional vector per diffusion sample. Returned when output_affinity_embedding is enabled on the affinity ligand.
- model_1_affinity_embedding (list[list[float]] | null): Embedding from affinity ensemble model 1.
- model_2_affinity_embedding (list[list[float]] | null): Embedding from affinity ensemble model 2.
metrics (dictionary): Runtime metrics for the request. Common keys include total_time_seconds, input_preparation_time_seconds, dataloader_setup_time_seconds, model_inference_time_seconds, postprocessing_time_seconds, response_construction_time_seconds, and affinity_prediction_time_seconds when affinity prediction runs.

Validation and Errors

Unknown request fields are rejected with HTTP 422 because the request schema does not allow additional properties.
Validation failures and processing errors return JSON shaped like {"error": "<message>"} rather than a FastAPI detail array.
Common validation failures include invalid sequence characters, duplicate ligand identifiers for affinity prediction, using output_affinity_embedding without predict_affinity on the same ligand, and providing structural templates for non-protein polymers.

Examples

Basic Protein Structure Prediction

Curl

Python

#!/bin/bash
# Create JSON payload for protein structure prediction
JSON='{
"polymers": [
    {
    "id": "A",
    "molecule_type": "protein",
    "sequence": "MALWMRLLPLLALLALWGPDPAAAFVNQHLCGSHLVEALYLVCGERGFFYTPKTRREAEDLQVGQVELGGGPGAGSLQPLALEGSLQKRGIVEQCCTSICSLYQLENYCN"
    }
],
"recycling_steps": 3,
"sampling_steps": 50,
"diffusion_samples": 1,
"step_scale": 1.638,
"output_format": "mmcif"
}'
# Make request
echo "Making request..."
curl -s -X POST \
-H "Content-Type: application/json" \
-d "$JSON" \
http://localhost:8000/biology/mit/boltz2/predict

Protein-Ligand Complex Prediction

Curl

Python

#!/bin/bash
# Create JSON payload for protein-ligand complex prediction
JSON='{
"polymers": [
    {
    "id": "A",
    "molecule_type": "protein",
    "sequence": "MALWMRLLPLLALLALWGPDPAAAFVNQHLCGSHLVEALYLVCGERGFFYTPKTRREAEDLQVGQVELGGGPGAGSLQPLALEGSLQKRGIVEQCCTSICSLYQLENYCN"
    }
],
"ligands": [
    {
    "id": "B1",
    "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O"
    }
],
"recycling_steps": 3,
"sampling_steps": 50,
"output_format": "mmcif"
}'
# Make request
echo "Making request..."
curl -s -X POST \
-H "Content-Type: application/json" \
-d "$JSON" \
http://localhost:8000/biology/mit/boltz2/predict

Example With Multiple Features

Curl

Python

#!/bin/bash
# Example combining polymers, a ligand, constraints, and output options
JSON='{
"polymers": [
    {
    "id": "A",
    "molecule_type": "protein",
    "sequence": "MALWMRLLPLLALLALWGPDPAAAFVNQHLCGSHLVEALYLVCGERGFFYTPKTRREAEDLQVGQVELGGGPGAGSLQPLALEGSLQKRGIVEQCCTSICSLYQLENYCN",
    "cyclic": false,
    "modifications": [
        {
        "ccd": "SEP",
        "position": 15
        }
    ]
    }
],
"ligands": [
    {
    "id": "L1",
    "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O"
    }
],
"constraints": [
    {
    "constraint_type": "pocket",
    "binder": "L1",
    "contacts": [
        {
        "id": "A",
        "residue_index": 25
        }
    ]
    }
],
"recycling_steps": 3,
"sampling_steps": 50,
"diffusion_samples": 1,
"step_scale": 1.638,
"without_potentials": false,
"output_format": "mmcif",
"concatenate_msas": false,
"write_full_pae": true,
"write_full_pde": true
}'
echo "Making comprehensive prediction request..."
curl -s -X POST \
-H "Content-Type: application/json" \
-d "$JSON" \
http://localhost:8000/biology/mit/boltz2/predict | jq '.'

PAE and PDE Outputs

The following example requests full PAE and PDE artifact writes. Aggregate PDE scores remain in the JSON response; full matrices are written under $NIM_OUTPUT_PATH as .npz files (ensure that path is mounted).

Curl

Python

#!/bin/bash
JSON='{
"polymers": [
    {
    "id": "A",
    "molecule_type": "protein",
    "sequence": "MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG"
    }
],
"diffusion_samples": 1,
"write_full_pae": true,
"write_full_pde": true
}'
response=$(curl -s -X POST \
-H "Content-Type: application/json" \
-d "$JSON" \
http://localhost:8000/biology/mit/boltz2/predict)
echo "Complex PDE score: $(echo "$response" | jq -r '.complex_pde_scores[0]')"
echo "Complex ipDE score: $(echo "$response" | jq -r '.complex_ipde_scores[0]')"
echo "JSON pae field (deprecated, always null): $(echo "$response" | jq -c '.pae')"
echo "JSON pde field (deprecated, always null): $(echo "$response" | jq -c '.pde')"
echo "Look for pae_*.npz / pde_*.npz under \$NIM_OUTPUT_PATH/prediction_*/"

Check Readiness

Endpoint path: /v1/health/ready

Input Parameters

None.

Outputs

The output of the endpoint is a JSON response with a value that indicates the readiness of the microservice. When the NIM is ready, it returns the response 200.

Example

Curl

Python

#!/bin/bash
URL=${NIM_URL:-"http://localhost:8000/v1/health/ready"}
curl -s -w "\nStatus code: %{http_code}\n" -H "Content-Type: application/json" $URL