--- title: "(ESM3) Generates an output track conditioned on inputs" method: POST path: "/api/v1/generate" tags: ["v1"] --- # (ESM3) Generates an output track conditioned on inputs `POST /api/v1/generate` ## Request - Base URL: `https://dev.evolutionaryscale.ai` (the document declares no server; this is the origin it was published from) - URL: `https://dev.evolutionaryscale.ai/api/v1/generate` - Auth: HTTP bearer ## Headers - `accept` string, nullable ## Request body - GenerateRequest - `model` 'esm3-open-2024-03', required: You may have access to additional, private models as well. These will be visible on the Rate Limits page under the Developer Console - `potential_sequence_of_concern` boolean: Disclose potential sequences of concern. For approved users, such sequences will not go through additional safety filtering. Reach out if you are interested in using this. - `track` string, required: Track to generate: sequence, structure, secondary_structure, sasa, or function. - `invalid_ids` integer[]: Token indices that should not be sampled. - `schedule` 'cosine' | 'linear': Unmasking schedule for generation. Controls the number of tokens to unmask during each round of iterative generation. - `strategy` 'random' | 'entropy': Unmasking strategy to use. Controls which tokens to unmask during each round of iterative generation. 'random' will unmask a correct number of tokens randomly. 'entropy' will unmask the tokens with the lowest logit entropy first. Default was random. Updated on 02/14/2025. - `num_steps` integer: Number of steps for generation. There is diminishing return for decoding steps more than 20. Note that this needs to be less than or equal to the sequence length. Default was 8. Updated on 02/14/2025. - `temperature` number: Temperature for sampling. Default was 1.0. Updated on 02/14/2025. - `temperature_annealing` boolean: Whether temperature should be annealed during generation. Default was False. Updated on 02/14/2025. - `top_p` number: Top-p sampling. - `condition_on_coordinates_only` boolean: Use coordinates instead of structure tokens as generation conditioning. - `inputs` Tracks, required - `sequence` string, nullable: Sequence of amino acids. As input, this can be partially masked out with `_` or the literal ``, for example to get logprob over masked positions - `secondary_structure` string, nullable: Secondary structure in 8-class DSSP format. Masked positions may be given as `_` or as the literal ``. - `sasa` union[], nullable: Solvent accessible surface area (SASA) as a list of floats. A position may also be a SASA vocab token: , , , <0-0.8>, <0.8-4.0>, <4.0-9.6>, <9.6-16.4>, <16.4-24.5>, <24.5-32.9>, <32.9-42.0>, <42.0-51.5>, <51.5-61.2>, <61.2-70.9>, <70.9-81.6>, <81.6-93.3>, <93.3-107.2>, <107.2-125.4>, <125.4-151.4>, <151.4-inf>. Nones are replaced with padding. 03/18/2025: A bug was fixed where 'inf' prior to this date was returned encoded as '-1', it will instead be 1000 going forward - union - integer - number - '' | '' | '' | '<0-0.8>' | '<0.8-4.0>' | '<4.0-9.6>' | '<9.6-16.4>' | '<16.4-24.5>' | '<24.5-32.9>' | '<32.9-42.0>' | '<42.0-51.5>' | '<51.5-61.2>' | '<61.2-70.9>' | '<70.9-81.6>' | '<81.6-93.3>' | '<93.3-107.2>' | '<107.2-125.4>' | '<125.4-151.4>' | '<151.4-inf>' - `function` array[], nullable: Function annotations, as a list of 3-tuples: (interpro tag, start, end). Start and end are 1-indexed, inclusive. We support interpro tags from version 95.0. - unknown[] - unknown - `coordinates` array[], nullable: Coordinates of the N, CA, C atom sequence as a Nx37x3 array. - array[] - number[] - `plddt` number[], nullable: Per position plddt predictions for a protein. Usually produced by structure decoder. - `ptm` number, nullable: Predicted TM score of a protein. Usually produced by structure decoder. - `crmsd` number, nullable: Constrained RMSD between the generated protein coordinates and the input protein coordinates. Produced by the generate endpoint. - `globularity` number, nullable: Globularity of the generated protein. Produced by the generate endpoint. - `interface` string[], nullable: Annotations on residues that participate in a multimer interface. - `interface_ptm` number, nullable: Interface TM score of a protein. - `pae` array[], nullable: Predicted Aligned Error matrix for the protein. Shape is L x L. Values are rounded to 2 decimals (well within 0.5 A bin width) - number[] - `only_compute_backbone_rmsd` boolean: Only compute the RMSD of the backbone atoms. Affects the returned crmsd. - `include_pae` boolean: Whether to include Predicted Aligned Error (PAE) matrix in the response. Local inference ignores this flag. ## Response `200` Successful Response - GenerateResponse - `model` 'esm3-open-2024-03', required: You may have access to additional, private models as well. These will be visible on the Rate Limits page under the Developer Console - `created` string, required: ISO formatted date time - `potential_sequence_of_concern` boolean: Indicate that the returned sequence may be of potential concerns. - `warning_messages` string[], nullable: Warning messages returned by FastAPI. - `outputs` Tracks - `sequence` string, nullable: Sequence of amino acids. As input, this can be partially masked out with `_` or the literal ``, for example to get logprob over masked positions - `secondary_structure` string, nullable: Secondary structure in 8-class DSSP format. Masked positions may be given as `_` or as the literal ``. - `sasa` union[], nullable: Solvent accessible surface area (SASA) as a list of floats. A position may also be a SASA vocab token: , , , <0-0.8>, <0.8-4.0>, <4.0-9.6>, <9.6-16.4>, <16.4-24.5>, <24.5-32.9>, <32.9-42.0>, <42.0-51.5>, <51.5-61.2>, <61.2-70.9>, <70.9-81.6>, <81.6-93.3>, <93.3-107.2>, <107.2-125.4>, <125.4-151.4>, <151.4-inf>. Nones are replaced with padding. 03/18/2025: A bug was fixed where 'inf' prior to this date was returned encoded as '-1', it will instead be 1000 going forward - union - integer - number - '' | '' | '' | '<0-0.8>' | '<0.8-4.0>' | '<4.0-9.6>' | '<9.6-16.4>' | '<16.4-24.5>' | '<24.5-32.9>' | '<32.9-42.0>' | '<42.0-51.5>' | '<51.5-61.2>' | '<61.2-70.9>' | '<70.9-81.6>' | '<81.6-93.3>' | '<93.3-107.2>' | '<107.2-125.4>' | '<125.4-151.4>' | '<151.4-inf>' - `function` array[], nullable: Function annotations, as a list of 3-tuples: (interpro tag, start, end). Start and end are 1-indexed, inclusive. We support interpro tags from version 95.0. - unknown[] - unknown - `coordinates` array[], nullable: Coordinates of the N, CA, C atom sequence as a Nx37x3 array. - array[] - number[] - `plddt` number[], nullable: Per position plddt predictions for a protein. Usually produced by structure decoder. - `ptm` number, nullable: Predicted TM score of a protein. Usually produced by structure decoder. - `crmsd` number, nullable: Constrained RMSD between the generated protein coordinates and the input protein coordinates. Produced by the generate endpoint. - `globularity` number, nullable: Globularity of the generated protein. Produced by the generate endpoint. - `interface` string[], nullable: Annotations on residues that participate in a multimer interface. - `interface_ptm` number, nullable: Interface TM score of a protein. - `pae` array[], nullable: Predicted Aligned Error matrix for the protein. Shape is L x L. Values are rounded to 2 decimals (well within 0.5 A bin width) - number[] ## Other responses - `422`: Validation Error ## Changes - **2026-09-23** `cfa834c15600`: 3 info - added the new optional `header` request parameter `accept` - added the new optional request property `include_pae` - added the media type `application/vnd.evolutionaryscale.pickle` for the response with the status `200` - **2026-09-01** `556ff7afc275`: 1 breaking, 1 info - response property `outputs/anyOf[#/components/schemas/Tracks]/sasa/anyOf[subschema #1]/items/` list-of-types was widened by adding types `string` to media type `application/json` of response `200` - request property `inputs/sasa/anyOf[subschema #1]/items/` list-of-types was widened by adding types `string` to media type `application/json` [Operation history](https://skmtc.dev/evolutionaryscale/apis/evolutionaryscale-api/changes/api/v1/generate/post.md) --- [API](https://skmtc.dev/evolutionaryscale/apis/evolutionaryscale-api.md) - [All operations](https://skmtc.dev/evolutionaryscale/apis/evolutionaryscale-api/llms.txt) - [OpenAPI document](https://skmtc.dev/evolutionaryscale/apis/evolutionaryscale-api/revisions/28a490b11fe1?raw)