Protein Design · Sequence prediction
ProteinMPNN API
Protein sequence prediction, to conform with backbone coordinates. Does not take external molecules into account. A useful step after RFDiffusion in a protein design pipeline, and before validation with structure prediction.
A graph neural network designed for protein inverse folding, meaning it predicts the amino acid sequences most likely to fold into a specific 3D protein backbone structure. By interpreting the spatial coordinates and geometric features of a target structure, the model generates sequence candidates. Researchers use ProteinMPNN for applications such as optimizing enzymes, designing novel therapeutics, and improving the stability or solubility of synthetic proteins.
Example presets
Send {"preset": "example_1/5L33"} to load an example and its bundled inputs. Add other request fields to override its settings. The schema includes all presets under tool.presets.
| preset | Description |
|---|---|
example_1/5L33 | Official submit_example_1.sh, applied to 5L33. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_1/6MRR | Official submit_example_1.sh, applied to 6MRR. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_2/3HTN | Official submit_example_2.sh, applied to 3HTN. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_2/4YOW | Official submit_example_2.sh, applied to 4YOW. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_3/3HTN | Official submit_example_3.sh, applied to 3HTN. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_3_score_only/3HTN | Official submit_example_3_score_only.sh, applied to 3HTN. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_3_score_only_from_fasta/3HTN | Official submit_example_3_score_only_from_fasta.sh, applied to 3HTN. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_4/3HTN | Official submit_example_4.sh, applied to 3HTN. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_4_non_fixed/3HTN | Official submit_example_4_non_fixed.sh, applied to 3HTN. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_5/3HTN | Official submit_example_5.sh, applied to 3HTN. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_4/4YOW | Official submit_example_4.sh, applied to 4YOW. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_4_non_fixed/4YOW | Official submit_example_4_non_fixed.sh, applied to 4YOW. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_5/4YOW | Official submit_example_5.sh, applied to 4YOW. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_6/4GYT | Official submit_example_6.sh, applied to 4GYT. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_6/6EHB | Official submit_example_6.sh, applied to 6EHB. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_7/5L33 | Official submit_example_7.sh, applied to 5L33. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_8/5L33 | Official submit_example_8.sh, applied to 5L33. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_7/6MRR | Official submit_example_7.sh, applied to 6MRR. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_8/6MRR | Official submit_example_8.sh, applied to 6MRR. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_pssm/3HTN | Official submit_example_pssm.sh, applied to 3HTN. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
example_pssm/4YOW | Official submit_example_pssm.sh, applied to 4YOW. Input files and the script’s sampling settings are included; folder examples run one structure per preset. Source ↗ |
Tasks
Pick a mode with task
Fields belonging to another task are ignored, so send only the ones for the task you chose.
| task | Mode |
|---|---|
design default |
Design sequences |
score_only |
Score sequences |
conditional_probs_only |
Conditional probabilities |
unconditional_probs_only |
Unconditional probabilities |
These local CLI options are not applicable to Bio Web and are omitted from its inputs:
out_folder: The service creates a separate output directory for each job and archives the results.path_to_model_weights: The model and soluble/CA-only controls select an installed official checkpoint.jsonl_path: This page accepts one structure per job; folder-based official examples are split into presets per PDB.chain_id_jsonl: pdb_path_chains supplies the designed chains; the other parsed chains are fixed context.
Request body
Fields
The same names the web form posts. See the field type table for what each kind means over HTTP.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
job_name
|
string text | no | proteinmpnn-demo |
Job name A label for this run and its results. |
pdb_path
|
string file | yes | — |
Backbone structure A single protein backbone to design or score. Leave chains blank to use every chain. In this form: Upload a PDB or mmCIF, or choose a preset with an included structure. The first model is used for multi-model structures. mmCIF is converted to PDB and requires single-character chain IDs. file types .pdb,.ent,.cif,.mmcif. |
pdb_path_chains
|
string text | no | — |
Chains to design or score Space-separated chain IDs, e.g. A C. Other chains supply fixed sequence and structural context. Blank selects all chains. |
path_to_fasta
score_only
|
string file | no | — |
Sequences to score (FASTA) Optional sequences for score-only mode. The native sequence is also scored. In this form: Supply one sequence per FASTA record, with designed chains in alphabetical order separated by /. Each chain must match its parsed backbone length. file types .fa,.fasta,.faa. |
model_name
|
string select | no | v_48_020 |
Model checkpoint
48-neighbor models trained with backbone noise of 0.02, 0.10, 0.20 or 0.30 angstroms. CA-only weights are available through v_48_020.
One of:
v_48_002, v_48_010, v_48_020, v_48_030.
|
use_soluble_model
|
boolean checkbox | no | false |
Use soluble-protein weights Use weights trained on soluble proteins. Cannot be combined with CA-only mode. |
ca_only
|
boolean checkbox | no | false |
Use CA-only structures and weights Use only alpha-carbon coordinates. Requires a CA-only checkpoint; v_48_030 is unavailable. |
num_seq_per_target
|
number number | no | 1 |
Samples per target Sequences per temperature in design mode; repeated evaluations in score/probability modes. Must be a multiple of batch size. In this form: This service accepts up to 1,000 samples per target. minimum 1, maximum 1000, step 1. |
batch_size
|
number number | no | 1 |
Batch size Samples processed together. Reduce if GPU memory runs out. Must divide the sample count exactly. minimum 1, maximum 1000, step 1. |
sampling_temp
design
|
string text | no | 0.1 |
Sampling temperatures One or more positive temperatures separated by spaces, e.g. 0.1 0.2 0.3. Higher values give more sequence diversity. |
seed
|
number number | no | 0 |
Random seed Zero chooses a random seed. Set a nonzero seed for reproducible sampling in the same runtime. minimum 0, maximum 2147483647, step 1. |
backbone_noise
|
number number | no | 0.0 |
Inference backbone noise Standard deviation in angstroms of Gaussian noise added to backbone coordinates during inference; separate from checkpoint training noise. minimum 0. |
max_length
|
number number | no | 200000 |
Maximum total sequence length Maximum parsed sequence length across all chains. Longer inputs are rejected before running. minimum 1, maximum 200000, step 1. |
fixed_positions_jsonl
|
string textarea | no | — |
Fixed positions (JSON) Positions whose native amino acids are retained, e.g. {"A": [1, 2, 3], "C": [10]}. Omitted chains are designed in full. In this form: Positions are 1-based indices in each parsed chain, including gaps and insertion-code residues, not PDB residue numbers. Enter the chain dictionary or the upstream dictionary keyed by structure name. |
tied_positions_jsonl
design
|
string textarea | no | — |
Tied positions (JSON) Groups sampled as the same amino acid, e.g. [{"A": [1], "C": [1]}, {"A": [2], "C": [2]}]. In this form: Uses the same 1-based parsed positions. Weighted groups also accept {"A": [[1], [0.5]], "C": [[1], [0.5]]}. |
homo_oligomer
design
|
boolean checkbox | no | false |
Tie all designed chains as a homo-oligomer Tie matching positions across the designed chains. Requires at least two chains of equal parsed length. In this form: Convenience equivalent of the official homooligomer helper. Use either this option or custom tied positions. |
omit_AAs
design
|
string text | no | X |
Omit amino acids One-letter amino-acid codes excluded from sampling everywhere, e.g. AC excludes alanine and cysteine. X excludes the unknown residue. |
bias_AA_jsonl
design
|
string textarea | no | — |
Global amino-acid bias (JSON) Bias for each amino acid, e.g. {"A": -1.1, "F": 0.7}. Positive values favor an amino acid; negative values discourage it. |
omit_AA_jsonl
design
|
string textarea | no | — |
Per-position omitted amino acids (JSON) Chain-specific exclusions, e.g. {"A": [[[1, 2], "CP"], [[3], "W"]]}. Uses 1-based parsed positions. In this form: Enter a chain dictionary or an upstream dictionary keyed by structure name. Missing chains have no local exclusions. |
bias_by_res_jsonl
design
|
string file | no | — |
Per-position amino-acid bias (JSON) Chain dictionary of L × 21 numeric bias matrices in alphabet order ACDEFGHIKLMNPQRSTVWYX. L is the parsed chain length. In this form: Upload JSON or provide an object through the API. An upstream dictionary keyed by structure name is also accepted. Missing chains receive zero bias. file types .json,.jsonl. |
pssm_jsonl
design
|
string file | no | — |
PSSM guidance (JSON) Chain dictionaries containing pssm_coef (L), pssm_bias (L × 21 probability distributions), and pssm_log_odds (L × 21). Alphabet: ACDEFGHIKLMNPQRSTVWYX. In this form: Use the output of the official make_pssm_input_dict.py helper, or a chain dictionary. The PSSM presets include converted official inputs. file types .json,.jsonl. |
pssm_multi
design
|
number number | no | 0.0 |
PSSM mixing weight Global PSSM weight from 0 to 1, multiplied by each position’s pssm_coef. Zero uses ProteinMPNN alone; one with coefficient one uses PSSM alone. minimum 0, maximum 1. |
pssm_bias_flag
design
|
boolean checkbox | no | false |
Mix in PSSM probabilities Enable probability mixing using pssm_multi and per-position pssm_coef. |
pssm_log_odds_flag
design
|
boolean checkbox | no | false |
Restrict amino acids using PSSM log odds Apply the PSSM log-odds mask to sampling. |
pssm_threshold
design
|
number number | no | 0.0 |
PSSM log-odds threshold Keep amino acids whose PSSM log odds are greater than this threshold when the log-odds option is enabled. |
conditional_probs_only_backbone
conditional_probs_only
|
boolean checkbox | no | false |
Condition only on the backbone For conditional probabilities, compute p(amino acid | backbone) instead of also conditioning on the other residues. |
save_score
design
|
boolean checkbox | no | false |
Save sampled sequence scores Save negative log probabilities for designed residues and global scores as NumPy .npz files. |
save_probs
design
|
boolean checkbox | no | false |
Save sampled sequence probabilities Save per-position probabilities, log probabilities, sequences, masks and chain order as NumPy .npz files. |
suppress_print
|
boolean checkbox | no | false |
Suppress progress output Suppress ProteinMPNN’s progress messages. Result files are still saved. |
Example
A request that runs
These are the defaults, exactly as the web form would post them.
curl -X POST https://athanortools.com/api/proteinmpnn/ \
-H 'Content-Type: application/json' \
-d '{
"task": "design",
"job_name": "proteinmpnn-demo",
"pdb_path": "",
"pdb_path_chains": "",
"model_name": "v_48_020",
"use_soluble_model": false,
"ca_only": false,
"num_seq_per_target": 1,
"batch_size": 1,
"sampling_temp": "0.1",
"seed": 0,
"backbone_noise": 0.0,
"max_length": 200000,
"fixed_positions_jsonl": "",
"tied_positions_jsonl": "",
"homo_oligomer": false,
"omit_AAs": "X",
"bias_AA_jsonl": "",
"omit_AA_jsonl": "",
"bias_by_res_jsonl": "",
"pssm_jsonl": "",
"pssm_multi": 0.0,
"pssm_bias_flag": false,
"pssm_log_odds_flag": false,
"pssm_threshold": 0.0,
"save_score": false,
"save_probs": false,
"suppress_print": false
}'
The reply is 202 with a queued job; poll its
status_url until status is
succeeded or failed. See
the quick start for the
whole exchange.
Responses
What comes back
| status | Meaning |
|---|---|
queued |
Accepted, waiting for the jobs ahead of it. `position` counts how many those are. |
running |
The tool is executing now. |
succeeded |
Finished; `result` holds the tool's output and `license` the terms it came under. |
failed |
Finished; `error` holds a code and a message. |
cancelled |
Abandoned at the submitter's request; there is no result. A job cancelled before its turn never ran at all. |
Errors
| code | Meaning |
|---|---|
invalid_input |
The client supplied invalid or incomplete input. |
tool_unavailable |
The requested third-party dependency is not available on this host. |
execution_failed |
A configured third-party tool exited unsuccessfully. |
internal_error |
An adapter failed in a way it does not describe. The detail is in the server log, not the response. |
not_found |
No job has that id. Finished jobs are dropped eventually. |