> This page is for OpenFold3, version 1.1.0. > 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 OpenFold3 NIM provides the following endpoint: - `/biology/openfold/openfold3/predict`: Predicts the 3D structure of a biomolecular complex from input sequences, including proteins, DNA, RNA, and ligands. ## Using the OpenFold3 NIM This section provides real examples of requests that should run when the NIM is correctly configured. **Note**: We recommend interacting with this endpoint using the Python `requests` module or similar HTTP client libraries for proper handling of complex JSON structures. ### Predict Structure The endpoint accepts requests where the data is formatted as specified in the [OpenAPI Specification](https://docs.nvidia.com/nim/bionemo/openfold3/1.1.0/api-reference/post-of-3-predict-biology-openfold-openfold-3-predict-post). #### Request Structure A request consists of: - **`request_id`** (optional): Identifier for the entire request. - **`inputs`** (required): List containing a single input specification. There can be at most one item in the list. Each input contains: - **`input_id`** (optional, recommended): Unique identifier for this structure prediction (for example, "my_protein_001") - **`molecules`** (required): List of molecules to predict as a complex (minimum 1 molecule) - **`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 has a required field: - **`type`**: Must be `"protein"`, `"dna"`, `"rna"`, or `"ligand"` Each molecule can have the following optional field: - **`id`**: Molecule / chain identifier(s) - single string or list of strings (1-4 alphanumeric characters each) - Use a list of distinct identifiers if the input is composed of multiple molecules with the same sequence, CCD code, or SMILES string. The following field is available and required for proteins, DNA, and RNA: - **`sequence`**: The amino acid or nucleotide sequence (1-4096 characters) The following field is available for protein and RNA sequences (see MSA Requirements): - **`msa`**: Single-chain multiple sequence alignment, refered to as `main MSA` in [ColabFold](https://github.com/sokrypton/ColabFold) The following field is available for protein sequences (see MSA Requirements): - **`paired_msa`**: Single-chain MSA, where the rows have been re-ordered in concert with the rows in the MSAs for other chains The following field is available for protein sequences to provide structural guidance: - **`structural_templates`**: List of structural templates in CIF format to guide structure prediction The following fields are available for Ligands: Only use either `ccd-codes` or `smiles` - **`ccd_codes`**: Chemical Component Dictionary code (for example, "ATP", "CL") - **`smiles`**: SMILES string representation (for example, "CC(=O)OC1=CC=CC=C1C(=O)O") #### MSA Structure The `msa` field is a nested dictionary with the following structure: ``` { "database_name": { "format": { "alignment": "alignment content as string", "format": "a3m" or "csv" } } } ``` MSA Requirements: - For each protein sequence, either the `msa` or `paired_msa` field is required. If your intent is to provide an MSA with 0 hits, then provide either an `msa` or `paired_msa` input containing only the query sequence. - For each RNA sequence, the `msa` is required. If your intent is to provide an MSA with 0 hits, then provide an `msa` input containing only the query sequence. - The first sequence in either the `msa` or `paired_msa` **must exactly match** the input protein or RNA sequence #### Recommended Workflow To predict the structure of a biomolecular complex: 1. Prepare the protein and RNA MSAs: - Run MSA tools for the distinct protein sequences in the complex, for example - [ColabFold](https://github.com/sokrypton/ColabFold) - Note: If your input is composed of multiple non-identical protein sequences, and you select a mode that uses pairing, you will have to post-process the `pair.a3m` file before inputting to the OpenFold3 NIM request. First filter null characters, then split by protein chain. - [OpenFold3 script](https://github.com/aqlaboratory/openfold-3) - Note: Has a colabfold mode, which for inputs with multiple non-identical protein sequences, writes the output of pairing separately for each chain. - [HHBlits](https://github.com/soedinglab/hh-suite) - Run MSA tools for the distinct RNA sequences in the complex - Convert results to A3M or CSV format - Ensure the first sequence in each MSA exactly matches your input sequence 2. Prepare the input sequences: - Proteins: Standard single-letter amino acid codes - DNA: Use A, T, C, G - RNA: Use A, U, C, G - Ligands: Find CCD codes from PDB or provide SMILES strings 3. Structure Your request: - Create a `molecules` list with all components of your complex - Add MSAs to each protein molecule and to each RNA molecule - Optionally assign molecule/chain IDs - Set `diffusion_samples` > 1 if you want multiple predictions 4. Submit the request and retrieve the structures: - POST the request to `/biology/openfold/openfold3/predict` - Parse the response to extract predicted structures - Structures are returned in ranked order (best first) ```python import requests import json # -------------------------------- # Parameters # -------------------------------- url = "http://localhost:8000/biology/openfold/openfold3/predict" headers = {"Content-Type": "application/json"} # Protein sequence protein_sequence = ( "LLYTRNDVSDSEKKATVELLNRQVIQFIDLSLITKQAHWNMRGANFIAVHEMLDGFRTALIDHLDTMAERAVQLGGVALGTTQVINSKTPLKSYPLDIHNVQDHLKELADRYAIVANDVRKAIGEAKDDDTADILTAASRDLDKFLWFIECNLDL" ) # MSA in CSV format - first sequence must match the query sequence protein_msa_csv = """key,sequence -1,LLYTRNDVSDSEKKATVELLNRQVIQFIDLSLITKQAHWNMRGANFIAVHEMLDGFRTALIDHLDTMAERAVQLGGVALGTTQVINSKTPLKSYPLDIHNVQDHLKELADRYAIVANDVRKAIGEAKDDDTADILTAASRDLDKFLWFIECNLDL -1,-FDTRHDLPAEVRSRMIALLNQQLADTFDLMSQTKQAHWNVKGPQFIALHEMFDEFAEGLAGYVDEIAERITALGGYAAGTVRMAAKASTLPDYPADVIADMDHVRALADRYAALAASTRKAIDEAGDLDTADLFTEVSRDLDKWLWFLEAH--- -1,LHPTRIDIPAEVRSQIAEILNQSLASTLDLKTQVKQAHWNVKGMDFYQLHELFDEMATELEEFIDLIAERITALGGVALGTARIAAERSTLPEYPIDILDGKSHVTALAERYAPYAKLVRDAIDSLGDADTADLYTEVSRAIDKRLWFLEAHL-- -1,-YPTRIDLPVEVRSQVVNLLNQTLAATLDLKTQSKQAHWNVKGMDFYQLHELFDELASELEEYVDMVAERVTALGGTALGTARIAAAESILPEYPLEAIDGADHVTALAERFAVYAKHLREAIDEAGDADTADLYTEISRTIDKRLWFLEAHL-- -1,LYPTRIDIPAEARKQIAGILNQTLAATSDLKSQAKQAHWNVKGTDFYQLHELFDEIAGELEEYIDMFAERITALGGYACGTVRMAAANSFLPEYPTDILMGMEHVTALAERFAPYAKQLREAIDDLGDADTADLYTEVSRTIDKRLWFLEAHL-- -1,MFRTKNDLSESIRGKAVELLNARLADAIDLQTQTKQAHWNIKGPNFIALHELFDKVNEDVEDYVDEIAERAVQLGGIAEGTARMAAKRSSLNEYPANTADGRSHVEALSSALAAFGKTARKAIDELGDADTADIFTEISRGIDKWLWFVEAHL-- -1,-FPTRVGIPAETRRRMINLLNQHLADAFDLYSQTKQAHWNVKGLQFIALHELFDKLAEDLEEAIDDMAERVTALGGTALGTVRIVAASSSIAEYPLDITDGPQHIEALAERFGRLAGMVRSAIDEAGDADTADLFTEVSRMLDKNLWFLEAH--- -1,-HKTRIDLAPEVREAMIELLNQQLADTFDLFSQTKQAHWNVKGPEFIALHGLFDDLADQLRDYVDKIAERATTLGGTAAGTVRMAASSTRLPEYPVEVFDGMAHVEALAERYAALAETTRAAIEEAGDISTADLFTEVSRGLDKALWLLEAHL-- -1,MYPTRNDLPESARIKLVELLNARLADAIDLQTQCKQAHWNVKGPDFIALHKLFDEVNDAVEEYVDLIAERAVQLGGVADGTARVAAKRSSLPEYPVRRGDGREHVEALSAVLSAFGKLVRAEIDELSDADTADLFTEVSRGVDKWLWFVEAHL-- -1,MRPTRIDLAPATREAMVELLNRQLADTLDLYTQTKQAHWNVTGPQFQQLHELFDELAGQLIGHLDLLAERATALGGAARGTLRMAAAVSRLPEMPAGFHDGLAVVRLLADRYAALAASTRAAIERAGDAATADLFTEISRALDKALWFLEAHL--""" # Paired MSA showing protein-protein interactions paired_msa_csv = """key,sequence -1,LLYTRNDVSDSEKKATVELLNRQVIQFIDLSLITKQAHWNMRGANFIAVHEMLDGFRTALIDHLDTMAERAVQLGGVALGTTQVINSKTPLKSYPLDIHNVQDHLKELADRYAIVANDVRKAIGEAKDDDTADILTAASRDLDKFLWFIECNLDL -1,-----IGIPTEKRTAIAEGLSRLLADTYTLYLKTHNYHWNVTGPMFQTLHTMFMTQYTELSLAVDEVAERIRALGHPAPGSYAAFARLSSIAE-EEAVPPSREMIANLVKGHEAVTRTARQVAESASDEPTCDLLTQRMQVSEKTAWMLRSLLD- -1,-----IGIEQADREAIAAGLNQLLADTYSLYLKTHSFHWNVTGPMFNTLHLMFEGQYTELALAVDVIAERVRALGARALGSYSAYAKLTQISE-DNGVSSAKAMIQELLEGQEIVIRNARPLVQKADDEATADLLTQRIQLHEKTAWMLRSLLE- -1,MYRSPSPLPEKTRASVVESLNARLADGLDLHSQIKVAHWNIKGPQFAALHPLFETFAVSLANHNDSIAERAVTLGGKAYGTTRHVGKASRLPEYPQETTKDLEHVKLLAERIEVYLDGLRESFVEVDDADSEDLATGIIVEFEKHAWFLRASLE- -1,-FPSHVNLPTDAREELIDSLNTLLADAIDLHWQIKQAHWNIRGRHFYSRHELFDDLAKHVRKQADEFAERAGTLGGYAEGTIRLAAKNSELPEYDLKAVDGDDHLKALVDRFARYGASIRTGIDELNDPVTSDLLTQTLGEVELDLWFLESHL-- -1,LYKSPSPLSEQARTAIAATLNERLSDGLDLHSQIKVAHWNIKGPQFAALHPLFETFAVSLANHNDSIAERAVTLGGRAYGTSRHVGKNSRLPEYPQETSRDLEHVKLLAERIEVYLSGLREAVEGHKDTDTVDLFTGIITEFEKHAWFLRASLE- -1,MYRSPSPLSEQVRAPLAASLNERLADGLDLHSQIKVAHWNIKGPQFAALHPLFETFAVSLSNHNDAIAERAVTLGGRAYGTSRHVGKASRIPEYQQETVKDLDHVKLLAERFDVYLAGLRESGEQHQDTDTVDLLTGAITEFEKHTWFLRATL-- -1,-FPSHINLPREARSELIDLLNTCLATAVDLHWQVKQAHWNIRGNHFISRHLLFDKVADHVRDHADEFAERAGALGGYAEGTIRLATKNSELEEYDLSAVNGDDHVRVIVDRVSRYAATIRDGIDELNDPVTADLLTQTLGTVEEDLWFLESHL-- -1,MYRSPSPLSEQTRSAVSATLNERLADGLDLHSQIKVAHWNIKGPQFAALHPLFETFAVSLAAHNDSVAERAVTLGGRAYGTSRHVAKTSRLPDYPQDTSKDLEHVRLLADRIESYLTGVRKVAEQHQDTDTVDLLTGIITEFEKHAWFLRASLE- -1,MYRSPSPLPAEARSQIVETLNARLIDGLDLHSQIKVAHWNIKGPHFAALHPLFETFAVSLAEFNDAIAERAVTLGGQIRATARHVASTSTIPDYDQSATRDLDHARLLADRFQKYLEGLRSIVDRLGDVDTSDLLTGIIGTFEKHTWFLRSTVE-""" # -------------------------------- # Assemble request content # -------------------------------- data = { # Request-level fields "request_id": "5xgo", # Optional: identifier for the entire request # Must contain exactly 1 input "inputs": [ { # Input-level fields "input_id": "5xgo", # Optional: identifier for this structure prediction # Molecules list - can contain multiple molecules that form a complex "molecules": [ { # Protein molecule "type": "protein", "id": ["A1", "A2"], # This protein spans two chains "sequence": protein_sequence, # MSA structure: {database_name: {format: {alignment, format}}} "msa": { "main_db": { # Arbitrary database name "csv": { # Format name (must be lowercase) "alignment": protein_msa_csv, # MSA content as string "format": "csv" # Format specification } } }, # Paired MSA for modeling chain-chain interactions "paired_msa": { "paired_db": { # Arbitrary database name "csv": { "alignment": paired_msa_csv, "format": "csv" } } } }, { # Ligand molecule using CCD code "type": "ligand", "id": ["M1", "M2"], # Two instances of this ligand "ccd_codes": "CL" # Chloride ion }, { # Another ligand molecule "type": "ligand", "id": ["N1", "N2"], # Two more instances "ccd_codes": "CL" } ], # Optional parameters "diffusion_samples": 1, # Number of structures to generate (1-5) "output_format": "cif" # Output format: "cif" or "pdb" } ] } # -------------------------------- # Post to server # -------------------------------- response = requests.post( url=url, data=json.dumps(data), headers=headers, timeout=600, # Longer timeout for complex structures ) # Check if the request was successful if response.ok: result = response.json() print("Request succeeded!") print(f"Generated {len(result.get('outputs', []))} structure(s)") else: print("Request failed:", response.status_code, response.text) ``` #### Response Structure The response contains: - **`request_id`**: Echo of the request ID - **`outputs`**: List with a single output object containing: - **`input_id`**: Echo of the input ID - **`structures_with_scores`**: List of predicted structures in ranked order (best first) - **`structure`**: The predicted structure in CIF or PDB format (as a string). - **`format`**: The format, `cif` or `pdb`. - **`confidence_score`**: The 'sample_ranking_score' i.e. confidence 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 the interfaces. ## Additional Examples ### Protein-Only Structure Prediction For predicting a simple protein structure without ligands: ```python data = { "inputs": [ { "input_id": "my_protein", "molecules": [ { "type": "protein", "sequence": "MKTVRQERLKSIVR", "msa": { "uniref90": { "a3m": { "alignment": """>query MKTVRQERLKSIVR >hit1 MKTVRQERLKSIVR >hit2 MKTVR-ERLKSIVR""", "format": "a3m" } } } } ] } ] } ``` ### Protein-DNA Complex For modeling protein-DNA interactions, see below. For double-stranded DNA (dsDNA), both complementary strands must be entered as separate molecules. ```python data = { "inputs": [ { "input_id": "protein_dna_complex", "molecules": [ { "type": "protein", "id": "A", "sequence": "MKTVRQERLKSIVR", "msa": { # ... MSA content ... } }, { "type": "dna", "id": "B", "sequence": "ATCGATCG" }, { "type": "dna", "id": "C", "sequence": "TAGCTAGC" } ] } ] } ``` ### Protein-Ligand with SMILES For modeling protein-ligand interactions using SMILES: ```python data = { "inputs": [ { "input_id": "protein_ligand", "molecules": [ { "type": "protein", "sequence": "MKTVRQERLKSIVR", "msa": { # ... MSA content ... } }, { "type": "ligand", "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O" # Aspirin } ] } ] } ``` ### Protein with Structural Templates For template-guided protein structure prediction using experimental or predicted structures: ```python # Read a template structure from a CIF file with open("template.cif", "r") as f: template_cif_content = f.read() data = { "inputs": [ { "input_id": "template_guided_prediction", "molecules": [ { "type": "protein", "sequence": "MKTVRQERLKSIVR", "msa": { "uniref90": { "a3m": { "alignment": """>query MKTVRQERLKSIVR >hit1 MKTVRQERLKSIVR""", "format": "a3m" } } }, "structural_templates": [ { "structure": template_cif_content, "format": "cif", "name": "template_1" } ] } ] } ] } ``` ## Field Reference The following sections describes the request-level, input-level, molecule-level, and AlignmentFileRecord fields, and the important validation rules. ### 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 | Required for proteins. Nested dict: database → format → AlignmentFileRecord | | `paired_msa` | No | dict | Protein/DNA/RNA | 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 constaining 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 (e.g., 'A', 'A1', 'B2'). 1-10 alphanumeric characters | ### Important Validation Rules Ensure you follow the rules when indicating values for the fields below: - **Protein MSAs**: The first sequence in the MSA must exactly match the input protein 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 ## MSA Format Requirements For proteins, the MSA is required and must meet these criteria: - The first sequence in the MSA must exactly match the input protein sequence - Gaps are represented by `-` characters - In A3M format, lowercase letters represent insertions relative to the query sequence - Both A3M and CSV formats are supported **A3M Format Example:** ``` >query MKTVRQERLKSIVR >hit1 MKTVRQERLKSIVR >hit2 MKTVR-ERLKSIVR ``` **CSV Format Example:** ``` key,sequence -1,MKTVRQERLKSIVR -1,MKTVRQERLKSIVR -1,MKTVR-ERLKSIVR ```