← API reference
Structure prediction

Protenix-v2 API

Structure prediction for proteins, DNA/RNA, ligands, and ions. Supports co-folding.

Protenix is ByteDance's trainable, open reproduction of AlphaFold 3. It predicts all-atom structures of biomolecular complexes, including proteins, DNA, RNA, ligands, ions, and covalent modifications, with optional MSA, template, RNA MSA, and pocket or contact constraint inputs.

Web form Documentation ↗ Input parameters ↗ Examples ↗ Home page ↗ Paper ↗ Source code ↗ License ↗
Submit POST /api/protenix/

Queues a run and returns 202 with the job.

Schema GET /api/protenix/

Returns this tool's metadata and the fields below, as JSON.

Runtime

Linux and a CUDA GPU are required. Installed by setup_system.sh into its own uv environment; model weights download on first use. · Python app (uv) · Expensive (min or hours)

License

Permissive. Apache 2.0 (ByteDance). Commercial use is permitted, with the licence's attribution and notice conditions.

Input method

Set input_mode to choose how inputs are supplied. Only fields for the selected method are used.

Example presets

Send {"preset": "quick_prediction"} to load an example and its bundled inputs. Add other request fields to override its settings. The schema includes all presets under tool.presets.

presetDescription
quick_predictionThe README's quick-prediction example: one 693-residue protein on protenix_base_default_v1.0.0. Its JSON carries no MSA paths, so Protenix searches for the protein MSA on the Protenix MSA server. Source ↗
protein_dna_ligand_7pzbOfficial co-folding example with a protein dimer, two DNA duplex components, and CCD ligand PCG. Its JSON carries no MSA paths, so Protenix searches for the protein MSA on the Protenix MSA server. Source ↗
precomputed_msas_7r6r_7wuxProtein–DNA (7R6R) and protein–ligand (7WUX) jobs from the official example.json with their supplied MSA files, run on protenix_base_default_v0.5.0 with its recommended parameters, as in inference_demo.sh. The deprecated msa directories are given as pairedMsaPath and unpairedMsaPath, the fields the docs recommend; the file's 7PZB job is the 7PZB preset. Source ↗
mini_esm_7r6r_7wuxThe same two jobs on the lightweight protenix_mini_esm_v0.5.0, which uses ESM2-3B embeddings in place of MSAs; its recommended parameters run 4 cycles and 5 diffusion steps, as in inference_demo.sh. Source ↗
constraints_7st3_5sakOfficial constraint example: an antibody–antigen complex with no constraint, a pocket constraint, and a token contact, and a protein–ligand complex with an atom contact, on protenix_base_constraint_v0.5.0. The example's 15 MB of precomputed MSAs are not bundled, so Protenix searches for them on the Protenix MSA server. Source ↗
rna_msa_9gmwOfficial RNA MSA example: an 86-nucleotide tRNA with its supplied RNA alignment, on protenix_base_default_v1.0.0 with its recommended parameters, as in inference_demo.sh. Source ↗
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 protenix-job Job name Names the single Protenix job generated from these parameters; results are written under this name. up to 80 characters.
sequence_molecules string (JSON array) molecule_builder yes [{"type": "protein", "id": "A", "count": 1, "sequence": "MSTNPKPQRKTKRNTNRRPQDVKFPGG", "cy … Molecules Add one box per unique Protenix entity. Set count and an optional matching list of comma-separated chain IDs, plus the sequence, ligand (a CCD_ code such as CCD_ATP, several joined for a glycan such as CCD_NAG_BMA_BGC, a SMILES string, or FILE_ and an absolute path to a 3D structure file), or ion code (e.g. MG, without CCD_). Modifications take a CCD code at a 1-based position. "Cyclic" closes a peptide with a head-to-tail amide bond. MSA and template paths are optional precomputed files. One of: protein, ligand, dna, rna, ion. A JSON array, sent as a string. See molecule entries.
covalent_bonds string textarea no — Covalent bonds (JSON, optional) Native Protenix covalent_bonds array, e.g. [{"entity1": "2", "copy1": 1, "position1": "2", "atom1": "N6", "entity2": "3", "copy2": 1, "position2": "1", "atom2": "C1"}]. Entities are 1-based box indexes; copies are 1-based within count and may be omitted together to bond every copy pair. up to 500000 characters.
constraint string textarea no — Constraint (JSON, optional) Native Protenix constraint object with a "contact" list and/or a "pocket" object, e.g. {"pocket": {"binder_chain": {"entity": 2, "copy": 1}, "contact_residues": [{"entity": 1, "copy": 1, "position": 69}], "max_distance": 8}}. A soft constraint, read only by protenix_base_constraint_v0.5.0. up to 20000 characters.
input_json string textarea yes [ { "name": "protenix-demo", "sequences": [ { "proteinChain": { … Protenix inference jobs (JSON) Complete native Protenix input: a non-empty top-level list of named jobs using proteinChain, dnaSequence, rnaSequence, ligand, or ion entities, with optional covalent_bonds, constraint, and modelSeeds. In this form: Bio Web writes this text to input.json. Any MSA, template, or FILE_ ligand paths inside it must be absolute paths available to the runner. up to 1000000 characters.
inputs_file string file no — Inference jobs file (JSON) The JSON file defining this run's jobs, in Protenix's own input format. In this form: Choose a file. Its contents are read here and sent as the input document. file types .json.
model string select no protenix-v2 Model Checkpoint to run; weights download on first use. protenix-v2 and the v1.0.0 base models add template and RNA MSA support; only protenix_base_constraint_v0.5.0 reads constraints; the mini and tiny models trade accuracy for speed (recommended: 4 cycles and 5 steps), and the ESM and ISM variants add ESM2-3B embeddings for use without MSAs. The protenix pred CLI default is protenix_base_default_v1.0.0. One of: protenix-v2, protenix_base_default_v1.0.0, protenix_base_20250630_v1.0.0, protenix_base_default_v0.5.0, protenix_base_constraint_v0.5.0, protenix_mini_esm_v0.5.0, protenix_mini_ism_v0.5.0, protenix_mini_default_v0.5.0, protenix_tiny_default_v0.5.0.
seeds string text no 101 Seeds Comma-separated integers passed to --seeds; every job runs once per seed. The CLI default is 101. up to 200 characters.
use_seeds_in_json boolean checkbox no false Use seeds from the input JSON Use modelSeeds from the first job in place of Seeds, for every job in the run.
samples number number no 5 Samples Number of structure samples per seed (--sample). The CLI default is 5. minimum 1, maximum 64, step 1.
cycles number number no 10 Pairformer cycles Number of Pairformer recycling cycles (--cycle). The CLI default is 10. minimum 1, maximum 100, step 1.
steps number number no 200 Diffusion steps Number of diffusion steps (--step). The CLI default is 200. minimum 1, maximum 1000, step 1.
use_default_params boolean checkbox no false Use the model's recommended parameters Replace cycles and steps with the selected model's recommended values: 10 and 200 for base models and protenix-v2, 4 and 5 for mini and tiny models. Also turns MSAs off for the mini ESM and ISM models.
use_msa boolean checkbox no true Use or generate protein MSAs Use protein MSA features. A protein without paired or unpaired MSA paths has its sequence sent to the MSA server chosen below. Turn off for private sequences or offline runs, at a significant cost in accuracy unless an ESM model is used.
msa_server_mode string select no protenix MSA server Where missing protein MSAs are searched: the Protenix MSA service (https://protenix-server.com/api/msa; set MMSEQS_SERVICE_HOST_URL on the runner to use your own) or the public ColabFold MMseqs2 server (https://api.colabfold.com). One of: protenix, colabfold.
use_template boolean checkbox no false Use protein templates Use template features from each protein's templatesPath (.a3m or .hhr). A protein without one gets a local template search instead, which needs protein MSAs, HMMER (hmmsearch and hmmbuild) on the runner's PATH, and downloads the PDB seqres database on first use. Requires protenix-v2 or a v1.0.0 base model.
use_rna_msa boolean checkbox no false Use RNA MSAs Use RNA MSA features from each RNA's unpaired MSA path. An RNA without one gets a local nhmmer search instead, which needs HMMER on the runner's PATH and downloads the Rfam, RNAcentral, and NT-RNA databases on first use. Requires protein MSAs to be on, and protenix-v2 or a v1.0.0 base model.
use_guidance boolean checkbox no false Use training-free guidance Apply Training-Free Guidance (--use_tfg_guidance) for improved ligand plausibility, such as chirality and planarity; increases compute time.
need_atom_confidence boolean checkbox no false Write atom-level confidence data Write full per-atom confidence JSON in addition to each sample's summary confidence.
dtype string select no bf16 Inference precision Protenix defaults to BF16; FP32 uses more memory. One of: bf16, fp32.
triatt_kernel string select no cuequivariance Triangle attention kernel Kernel for triangle attention. DeepSpeed needs DeepSpeed and CUTLASS_PATH on the runner; PyTorch needs no extra kernels. One of: cuequivariance, triattention, deepspeed, torch.
trimul_kernel string select no cuequivariance Triangle multiplicative kernel Kernel for the triangle multiplicative update. One of: cuequivariance, torch.
enable_cache boolean checkbox no true Cache diffusion variables Cache shareable variables in the diffusion module.
enable_fusion boolean checkbox no true Kernel fusion Enable efficient kernel fusion in the diffusion transformer.
enable_tf32 boolean checkbox no true TF32 matrix multiplication Enable TF32 for FP32 matrix multiplications on supported GPUs.

Molecule entry keys

KeyMeaning
type Which of the field's molecule types this entry is.
id A chain/entity ID, or a list of IDs for identical copies. Tools with configurable IDs expose this inside each molecule box. CatPred, whose boxes are not chains of one structure, uses it for the enzyme's sequence ID (its pdbpath, which must name exactly one sequence) and for a substrate's optional label.
count The number of identical copies. Used by tools whose native schema represents copy count separately from IDs.
sequence The residues, for a protein, dna, or rna entry.
ligand A SMILES string or a CCD_ code, for a ligand entry. CatPred resolves no CCD codes and takes SMILES only.
ion An ion code, for an ion entry.
cyclic Whether a polymer chain is cyclic. Tools that cannot model one reject it rather than ignoring it.
modifications Substitutions, as {"position": <integer>, "residue": "<CCD code>"} objects. Position indexing follows the tool: ESMFold2 uses zero-based positions; the other molecule-builder tools use one-based positions.
msa A tool-native MSA for supported protein/RNA entities. Boltz-2: an absolute .a3m/.csv path, or empty for single-sequence; omit it to generate one with the MSA server. ESMFold2: an absolute .a3m path, a serialized MSA, or a {"sequences": [...]} object.
paired_msa_path An OpenDDE or Protenix protein paired-MSA path.
unpaired_msa_path An OpenDDE or Protenix protein or RNA unpaired-MSA path.
templates_path An OpenDDE or Protenix protein template-hits path.
Example

A request that runs

These are the defaults, exactly as the web form would post them.

curl -X POST https://athanortools.com/api/protenix/ \
  -H 'Content-Type: application/json' \
  -d '{
  "input_mode": "parameters",
  "job_name": "protenix-job",
  "sequence_molecules": "[{\"type\": \"protein\", \"id\": \"A\", \"count\": 1, \"sequence\": \"MSTNPKPQRKTKRNTNRRPQDVKFPGG\", \"cyclic\": false, \"modifications\": []}]",
  "covalent_bonds": "",
  "constraint": "",
  "model": "protenix-v2",
  "seeds": "101",
  "use_seeds_in_json": false,
  "samples": 5,
  "cycles": 10,
  "steps": 200,
  "use_default_params": false,
  "use_msa": true,
  "msa_server_mode": "protenix",
  "use_template": false,
  "use_rna_msa": false,
  "use_guidance": false,
  "need_atom_confidence": false,
  "dtype": "bf16",
  "triatt_kernel": "cuequivariance",
  "trimul_kernel": "cuequivariance",
  "enable_cache": true,
  "enable_fusion": true,
  "enable_tf32": true
}'

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

statusMeaning
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

codeMeaning
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.