> This page is for OpenFold3, version 1.6.0 (Latest) (default).
> For other versions, use one of these documentation indexes:
> - 1.6.0 (Latest) (default): https://docs.nvidia.com/nim/bionemo/openfold3/1.6.0/llms.txt
> - 1.5.0: https://docs.nvidia.com/nim/bionemo/openfold3/1.5.0/llms.txt
> - 1.4.0: https://docs.nvidia.com/nim/bionemo/openfold3/1.4.0/llms.txt
> - 1.3.0: https://docs.nvidia.com/nim/bionemo/openfold3/1.3.0/llms.txt
> - 1.2.0: https://docs.nvidia.com/nim/bionemo/openfold3/1.2.0/llms.txt
> - 1.1.0: https://docs.nvidia.com/nim/bionemo/openfold3/1.1.0/llms.txt
> - 1.0.0: https://docs.nvidia.com/nim/bionemo/openfold3/1.0.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nim/bionemo/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nim/bionemo/_mcp/server.

# Example Requests

## Use the OpenFold3 NIM

OpenFold3 NIM predicts 3D structures of biomolecular complexes including proteins, DNA, RNA, and ligands. The NIM supports multiple prediction modes: protein-only structure prediction, protein-DNA/RNA complexes, protein-ligand interactions, and template-guided predictions.

## Try It Out

The following example shows a basic protein structure prediction. This script predicts the structure of a small protein and saves the result.

```python
import requests

# NIM endpoint
url = "http://localhost:8000/biology/openfold/openfold3/predict"
headers = {"Content-Type": "application/json"}

# Define protein sequence
protein_sequence = "MKTVRQERLKSIVR"

# Create minimal MSA (just the query sequence)
msa_content = f">query\n{protein_sequence}"

# Build the request
data = {
    "inputs": [{
        "input_id": "my_first_prediction",
        "molecules": [{
            "type": "protein",
            "sequence": protein_sequence,
            "msa": {
                "main": {
                    "a3m": {
                        "alignment": msa_content,
                        "format": "a3m"
                    }
                }
            }
        }],
        "output_format": "pdb"
    }]
}

# Submit prediction request
response = requests.post(url, json=data, headers=headers, timeout=300)

# Extract and save the predicted structure
if response.ok:
    result = response.json()
    structure = result['outputs'][0]['structures_with_scores'][0]['structure']
    
    # Save to file
    with open("predicted_structure.pdb", "w") as f:
        f.write(structure)
    
    print("✓ Prediction complete! Structure saved to predicted_structure.pdb")
else:
    print(f"✗ Prediction failed: {response.status_code} - {response.text}")
```

Save this script as `predict.py` and run it:

```bash
python predict.py
```

## Try Out Other Prediction Use Cases

The following examples show how to customize the `data` field for different prediction scenarios. To try them, replace the `data` dictionary in the script above with these examples.

### Protein-DNA Complex

Use this example for modeling protein-DNA interactions. For double-stranded DNA (dsDNA), both complementary strands must be entered as separate molecules.

```python
# Replace the 'data' variable with this
data = {
    "inputs": [{
        "input_id": "protein_dna_complex",
        "molecules": [
            {
                "type": "protein",
                "id": "A",
                "sequence": "MKTVRQERLKSIVR",
                "msa": {
                    "main": {
                        "a3m": {
                            "alignment": ">query\nMKTVRQERLKSIVR",
                            "format": "a3m"
                        }
                    }
                }
            },
            {
                "type": "dna",
                "id": "B",
                "sequence": "ATCGATCG"
            },
            {
                "type": "dna",
                "id": "C",
                "sequence": "CGATCGAT"  # Complementary strand
            }
        ],
        "output_format": "pdb"
    }]
}
```

### Protein-Ligand With SMILES

For modeling protein-ligand interactions using SMILES notation:

```python
# Replace the 'data' variable with this
data = {
    "inputs": [{
        "input_id": "protein_ligand",
        "molecules": [
            {
                "type": "protein",
                "sequence": "MKTVRQERLKSIVR",
                "msa": {
                    "main": {
                        "a3m": {
                            "alignment": ">query\nMKTVRQERLKSIVR",
                            "format": "a3m"
                        }
                    }
                }
            },
            {
                "type": "ligand",
                "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O"  # Aspirin
            }
        ],
        "output_format": "pdb"
    }]
}
```

### Protein-Ligand With CCD Code

For modeling protein-ligand interactions using Chemical Component Dictionary codes:

```python
# Replace the 'data' variable with this
data = {
    "inputs": [{
        "input_id": "protein_ligand_ccd",
        "molecules": [
            {
                "type": "protein",
                "sequence": "MKTVRQERLKSIVR",
                "msa": {
                    "main": {
                        "a3m": {
                            "alignment": ">query\nMKTVRQERLKSIVR",
                            "format": "a3m"
                        }
                    }
                }
            },
            {
                "type": "ligand",
                "ccd_codes": "ATP"  # Adenosine triphosphate
            }
        ],
        "output_format": "pdb"
    }]
}
```

### Protein With Structural Templates

For template-guided protein structure prediction using experimental or predicted structures:

<Note>
Structural templates can significantly improve prediction accuracy. For detailed information on template processing, selection strategies, and best practices, refer to [Template Processing](/nim/bionemo/openfold3/template-processing).
</Note>

```python
# First, read a template structure from a CIF file
with open("template.cif", "r") as f:
    template_cif_content = f.read()

# Replace the 'data' variable with this
data = {
    "inputs": [{
        "input_id": "template_guided_prediction",
        "molecules": [{
            "type": "protein",
            "sequence": "MKTVRQERLKSIVR",
            "msa": {
                "main": {
                    "a3m": {
                        "alignment": ">query\nMKTVRQERLKSIVR",
                        "format": "a3m"
                    }
                }
            },
            "structural_templates": [
                {
                    "structure": template_cif_content,
                    "format": "cif",
                    "name": "template_1"
                }
            ]
        }],
        "output_format": "pdb"
    }]
}
```

### Multi-Chain Protein Complex With MSAs

For predicting complex biomolecular assemblies with multiple protein chains and detailed MSAs:

```python
# Multi-chain protein sequences
protein1_sequence = "VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVAHVDDMPNALSALSDLHAHKLRVDPVNFKLLSHCLLVTLAAHLPAEFTPAVHASLDKFLASVSTVLTSKYR"

protein2_sequence = "VHLTPEEKSAVTALWGKVNVDEVGGEALGRLLVVYPWTQRFFESFGDLSTPDAVMGNPKVKAHGKKVLGAFSDGLAHLDNLKGTFATLSELHCDKLHVDPENFRLLGNVLVCVLAHHFGKEFTPPVQAAYQKVVAGVANALAHKYH"

# MSA for protein 1 with multiple homologs (a3m format)
protein1_msa_a3m = """>101
VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVAHVDDMPNALSALSDLHAHKLRVDPVNFKLLSHCLLVTLAAHLPAEFTPAVHASLDKFLASVSTVLTSKYR
>UniRef100_A0A068F5F5
VLSAKDKTNIKTAWGKIGGHAAEYGAEALERMFVVYPTTKTYFPHFDVSHGSAQVKAHGKKVADALTNAVGHLDDLPGALSALSDLHAHKLRVDPVNFKLLSHCLLVTLANHIPADFTPAVHASLDKFLASVSTVLTSKYR
>UniRef100_A0A091II63
-LTQAEKAAVVAIWAKVAPQIDAIGAESLERLFFTYPQTKTYFPHFDLSHSSPQLRGHGSKVMNAIGEAVKNLDDLRGALVKLSELHAYILRVDPVNFKLLSHCILCSLAAHYPKDFTPEAHAAWDKFLSSVSSVLTEKYR
>UniRef100_UPI00162A5CD8
VLSPADKTNIKAAWDKVGGNVGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVGDALTNAVAHIDDLPGALSALSDLHAYKLRVDPVNFKLLSHCLLVTLASHLPSDFTPAVHASLDKFLASVSTVLTSKYR"""

# Paired MSA for protein 1 for modeling chain-chain interactions
protein1_paired_msa_a3m = """>101
VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVAHVDDMPNALSALSDLHAHKLRVDPVNFKLLSHCLLVTLAAHLPAEFTPAVHASLDKFLASVSTVLTSKYR
>UniRef100_UPI001EFC6C5E
-LTDEQKRLIQKSYAEIDRQSSNFAAIFYDCLFAMAPLIRPMFK-----SERPVFEYHFNELISTAATKVFQFEEIKPRLVVLGRKH-RGYGVTPAQFDVVRSALMLSIQDCLRDACNPAIEQAWSSYYDEIAKVM-----
>UniRef100_UPI0018E7FE8A
-LTEIEKEAITSSFTLINHQEQQFASFFYDCLFDLAPLIKPMFKR-----DRKLIEEHFYMIFCAAVDNIHHLDTIRSTLLELGSRH-RNYGVKVSHFPIVKSALILAIQHELKGQSNTDIENAWSNYYDELAAII-----"""

# MSA for protein 2 with multiple homologs (a3m format)
protein2_msa_a3m = """>102
VHLTPEEKSAVTALWGKVNVDEVGGEALGRLLVVYPWTQRFFESFGDLSTPDAVMGNPKVKAHGKKVLGAFSDGLAHLDNLKGTFATLSELHCDKLHVDPENFRLLGNVLVCVLAHHFGKEFTPPVQAAYQKVVAGVANALAHKYH
>UniRef100_UPI0018F66524
VHLSAEEKSAVNSLWGKVNVEEHGGEALARLLVVYPWTQRFFDSFGNLSSASAILGNPKVKAHGKKVLTSFGDAVKNLDNLKGTFAKLSELHCDKLHVDPENFRLLGNVLVVVLARHFGKDFTPEVQAAWQKLVAGVASALAHKYH
>UniRef100_UPI001CFCA915
VHFTAEEKSTITSLWGKVNVEETGGEALGRLLVVYPWTQRFFDSFGNLSSPSAILGNPKVKAHGKKVLTSLGDAVKNLDNLKGAFSKLSELHCDKLHVDPENFRLLGNVLIVVLAAHFGKEFTPEVQAAWQKLVTGVASALAHKYH
>UniRef100_A0A8C6RZS6
VNFTPEEKSLVTSLWSKVNVEEAGGEALGRLLVVYPWTQRFFDSFGNLSSASAIMGNPRVKAHGKKVLTSFGEAVKNMDNLKATFSKLSELHCDKLHVDPENFKLLGNVLVVVLASHFGKEFTPEVQAAWQKLVAGVANALSHKYH"""

# Paired MSA for protein 2 for modeling chain-chain interactions
protein2_paired_msa_a3m = """>102
VHLTPEEKSAVTALWGKVNVDEVGGEALGRLLVVYPWTQRFFESFGDLSTPDAVMGNPKVKAHGKKVLGAFSDGLAHLDNLKGTFATLSELHCDKLHVDPENFRLLGNVLVCVLAHHFGKEFTPPVQAAYQKVVAGVANALAHKYH
>UniRef100_UPI001EFC6C5E
--LTDEQKRLIQKSYAEIDrqSSNFAAIFYDCLFAMAPLIRPMFKS-----------ERPVFEYHFNELISTAATKVFQFEEIKPRLVVLGRKH-RGYGVTPAQFDVVRSALMLSIQDCLRDACNPAIEQAWSSYYDEIAKVM-----
>UniRef100_UPI0018E7FE8A
--LTEIEKEAITSSFTLINHQEqqFASFFYDCLFDLAPLIKPMFKRDRKL-----------IEEHFYMIFCAAVDNIHHLDTIRSTLLELGSRH-RNYGVKVSHFPIVKSALILAIQHELKGQSNTDIENAWSNYYDELAAIILEG--"""

# Replace the 'data' variable with this
data = {
    "request_id": "1a3n",
    "inputs": [{
        "input_id": "1a3n",
        "molecules": [
            {
                "type": "protein",
                "id": ["A", "C"],
                "sequence": protein1_sequence,
                "msa": {
                    "uniref": {
                        "a3m": {
                            "alignment": protein1_msa_a3m,
                            "format": "a3m"
                        }
                    }
                },
                "paired_msa": {
                    "paired": {
                        "a3m": {
                            "alignment": protein1_paired_msa_a3m,
                            "format": "a3m"
                        }
                    }
                }
            },
            {
                "type": "protein",
                "id": ["B", "D"],
                "sequence": protein2_sequence,
                "msa": {
                    "uniref": {
                        "a3m": {
                            "alignment": protein2_msa_a3m,
                            "format": "a3m"
                        }
                    }
                },
                "paired_msa": {
                    "paired": {
                        "a3m": {
                            "alignment": protein2_paired_msa_a3m,
                            "format": "a3m"
                        }
                    }
                }
            }
        ],
        "diffusion_samples": 1,
        "output_format": "pdb"
    }]
}
```

## Understand the API

This section provides detailed information about the OpenFold3 NIM API structure, requirements, and validation rules.

### Endpoint

- `/biology/openfold/openfold3/predict`: Predicts the 3D structure of a biomolecular complex from input sequences

### Request Structure

A complete request consists of:

**Request-Level Fields:**
- **`request_id`** (optional): Identifier for the entire request (max 128 characters)
- **`inputs`** (required): List containing exactly one input specification

**Input-Level Fields:**
- **`input_id`** (optional): Unique identifier for this structure prediction (max 128 characters, default: "input_id_0")
- **`molecules`** (required): List of molecules to predict as a complex (minimum 1)
- **`diffusion_samples`** (optional): Number of independent structures to generate (1-5, default: 1)
- **`output_format`** (optional): Output format - `"cif"` (default) or `"pdb"`

### Molecule Specification

Each molecule in the `molecules` list requires:

**Common Fields:**
- **`type`** (required): Must be `"protein"`, `"dna"`, `"rna"`, or `"ligand"`
- **`id`** (optional): Chain identifier(s) - single string or list of strings (1-4 alphanumeric characters each)

**For Proteins, DNA, RNA:**
- **`sequence`** (required): Amino acid or nucleotide sequence (1-4096 characters)
  - Proteins: Standard single-letter amino acid codes
  - DNA: A, T, C, G
  - RNA: A, U, C, G

**For Proteins (MSA required):**
- **`msa`** (conditional): Single-chain multiple sequence alignment (required unless `paired_msa` provided)
- **`paired_msa`** (optional): Joint MSA for modeling chain-chain interactions
- **`structural_templates`** (optional): List of structural templates in CIF format

**For RNA (MSA required):**
- **`msa`** (required): Single-chain multiple sequence alignment

**For Ligands (one required):**
- **`ccd_codes`** (conditional): Chemical Component Dictionary code (for example, "ATP", "CL")
- **`smiles`** (conditional): SMILES string (for example, "CC(=O)OC1=CC=CC=C1C(=O)O")

<Note>
For proteins, either `msa` or `paired_msa` is required. If you want to provide an MSA with 0 hits, include an MSA containing only the query sequence.
</Note>

### MSA Structure

The `msa` and `paired_msa` fields use a nested dictionary structure:

```python
"msa": {
    "database_name": {        # Arbitrary name (for example, "uniref90", "main_db")
        "format_name": {      # Must be "a3m" or "csv" (lowercase)
            "alignment": "...",   # MSA content as string
            "format": "csv"       # Must match format_name
        }
    }
}
```

**MSA Requirements:**
- First sequence must exactly match the input protein/RNA sequence (without gaps)
- Format names must be lowercase: `"a3m"` or `"csv"`
- Maximum 3 MSA databases per protein
- Gaps represented by `-` characters
- A3M format: lowercase letters represent insertions relative to query

**A3M Format Example:**

```text
>query
MKTVRQERLKSIVR
>hit1
MKTVRQERLKSIVR
>hit2
MKTVR-ERLKSIVR
```

**CSV Format Example:**

```text
key,sequence
-1,MKTVRQERLKSIVR
-1,MKTVRQERLKSIVR
-1,MKTVR-ERLKSIVR
```

### Structural Templates

For template-guided predictions, each template requires:

- **`structure`** (required): CIF file contents as string
- **`format`** (required): Must be `"cif"`
- **`name`** (optional): Template identifier
- **`chain_id`** (optional): Specific chain to use from multi-chain CIF (1-10 alphanumeric characters)

### Prepare MSAs

For production use, generate MSAs using sequence homology search tools:

**Recommended Tools:**
- [ColabFold](https://github.com/sokrypton/ColabFold) - Fast MSA generation
  - For multi-chain inputs with pairing, post-process the `pair.a3m` file by filtering null characters and splitting by chain
- [OpenFold3 MSA script](https://github.com/aqlaboratory/openfold-3) - Includes colabfold mode with automatic chain splitting
- [HHBlits](https://github.com/soedinglab/hh-suite) - Traditional MSA generation

**Workflow:**
1. Run MSA tools for each distinct protein/RNA sequence
2. Convert results to A3M or CSV format
3. Ensure first sequence matches your input sequence exactly
4. For multi-chain complexes, optionally generate paired MSAs

### Response Structure

The response contains:

- **`request_id`**: Echo of the request ID
- **`outputs`**: List with a single output object:
  - **`input_id`**: Echo of the input ID
  - **`structures_with_scores`**: List of predicted structures (ranked, best first):
    - **`structure`**: Predicted structure in CIF or PDB format (string)
    - **`format`**: Output format (`"cif"` or `"pdb"`)
    - **`confidence_score`**: Sample ranking score
    - **`complex_plddt_score`**: Average pLDDT score for the complex
    - **`complex_pde_score`**: Average PDE score for the complex
    - **`ptm_score`**: Predicted TM score for the complex
    - **`iptm_score`**: Predicted TM score for interfaces
  - **`runtime_metrics`** (optional): Performance metrics

### Field Reference Tables

#### Request-Level Fields

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `request_id` | No | string | Identifier for the entire request (max 128 characters) |
| `inputs` | Yes | list | Must contain exactly 1 input specification |

#### Input-Level Fields

| Field | Required | Type | Default | Description |
|-------|----------|------|---------|-------------|
| `input_id` | No | string | "input_id_0" | Unique identifier for this structure prediction (max 128 characters) |
| `molecules` | Yes | list | - | List of molecules to predict (minimum 1) |
| `diffusion_samples` | No | integer | 1 | Number of independent structures to generate (1-5) |
| `output_format` | No | string | "cif" | Output format: `"cif"` or `"pdb"` |

#### Molecule Fields

| Field | Required | Type | Valid For | Description |
|-------|----------|------|-----------|-------------|
| `type` | Yes | string | All | Must be `"protein"`, `"dna"`, `"rna"`, or `"ligand"` |
| `sequence` | Conditional | string | Protein/DNA/RNA | Amino acid or nucleotide sequence (1-4096 characters) |
| `msa` | Conditional | dict | Protein/RNA | Required for proteins (unless paired_msa provided) and RNA. Nested dict: database → format → AlignmentFileRecord |
| `paired_msa` | No | dict | Protein | Joint MSA for modeling chain-chain interactions |
| `structural_templates` | No | list | Protein | List of structural templates in CIF format to guide prediction |
| `ccd_codes` | Conditional | string | Ligand | CCD code (1-5 uppercase letters/numbers). Mutually exclusive with `smiles` |
| `smiles` | Conditional | string | Ligand | SMILES string. Mutually exclusive with `ccd_codes` |
| `id` | No | string or list | All | Chain identifier(s). 1-4 alphanumeric characters each |

#### AlignmentFileRecord Fields

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `alignment` | Yes | string | MSA content as a string |
| `format` | Yes | string | Format type: `"a3m"`, `"csv"` (lowercase required) |
| `rank` | No | integer | Ordering rank for concatenating alignments (default: -1) |

#### StructuralTemplate Fields

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `structure` | Yes | string | The contents of the file containing the structural template, in CIF format |
| `format` | Yes | string | Format type: must be `"cif"` |
| `name` | No | string | Optional name to identify the template |
| `chain_id` | No | string | Optional chain ID to use from multi-chain CIF files. If not specified, the best matching chain is automatically selected. Supports CIF format (for example, 'A', 'A1', 'B2'). 1–10 alphanumeric characters |

### Important Validation Rules

Ensure you follow these rules when specifying field values:

- **Protein MSAs**: The first sequence in the MSA must exactly match the input protein sequence (without gaps)
- **RNA MSAs**: The first sequence in the MSA must exactly match the input RNA sequence (without gaps)
- **Chain IDs**: Must be 1-4 alphanumeric characters. PDB output format only supports single-character IDs
- **MSA Format Names**: Must be lowercase (`"a3m"`, not `"A3M"`)
- **Ligand Specification**: Must provide either `ccd_codes` or `smiles`, not both
- **Sequence Length**: Maximum 4096 characters per molecule
- **Database Limit**: Maximum 3 MSA databases per protein
- **Structural Templates**: Only allowed for protein molecules and must be in CIF format