Endpoints

Molecular Generation

Endpoint path: /generate

Input Parameters

• smiles (string): Optional (default: null). SAFE or SMILES text with optional masks as the molecular template for generation. When null, performs de novo generation.
• num_molecules (integer, 1~1000): Optional (default: 30). Maximum number of molecules to generate. The actual count returned may be lower since invalid generations are filtered out.
• temperature (float, 0.01~10.0): Optional (default: 1.0). Temperature scaling factor for SoftMax sampling.
• noise (float, 0.0~2.0): Optional (default: 1.0). Randomness factor used during diffusion sampling.
• gamma (float, 0.0~1.0): Optional (default: 0.0). Classifier-free guidance strength. Set to 0 to disable.
• min_add_len (integer, 1~128): Optional (default: 24). Minimum number of MASK tokens to add for generation.
• step_size (integer, 1~10): Optional. Deprecated in v2.0.0 and accepted only for backward compatibility. The service ignores this field.
• scoring (enum, QED or LogP): Optional (default: QED). Method used to score and rank generated molecules.
• unique (boolean): Optional (default: false). When set, returns only unique molecules by removing duplicates.
• filter (boolean): Optional (default: false). When enabled, removes generated molecules that do not contain the input fragment as a substructure (fragment-preservation validation). The default is false for backward compatibility. Enabling filter may reduce the number of returned molecules.

Outputs

The output is a JSON response with:

• status: success or failed
• molecules: On success, a list of generated molecules with smiles and score
• error: On failure, a short error message

Example

curl --request POST --url "http://127.0.0.1:8000/generate" \
  --header "Content-Type: application/json" \
  --data '{
    "smiles": "[C@H]1O[C@@H](CO)[C@H](O)[C@@H]1O.[*{15-15}]",
    "num_molecules": 5,
    "temperature": 1.0,
    "noise": 1.0,
    "scoring": "QED"
  }'

import json
import requests
session = requests.Session()
response = session.post(
    "http://127.0.0.1:8000/generate",
    headers={"Accept": "application/json"},
    json={
        "smiles": "[C@H]1O[C@@H](CO)[C@H](O)[C@@H]1O.[*{15-15}]",
        "num_molecules": 5,
        "temperature": 1.0,
        "noise": 1.0,
        "scoring": "QED",
    },
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Example With Fragment Filtering

Use filter: true to retain only molecules that preserve the input fragment as a substructure. The returned count may be lower than num_molecules when filtering is active.

curl --request POST --url "http://127.0.0.1:8000/generate" \
  --header "Content-Type: application/json" \
  --data '{
    "smiles": "[C@H]1O[C@@H](CO)[C@H](O)[C@@H]1O.[*{15-15}]",
    "num_molecules": 10,
    "temperature": 1.0,
    "noise": 1.0,
    "scoring": "QED",
    "filter": true
  }'

import json
import requests
session = requests.Session()
response = session.post(
    "http://127.0.0.1:8000/generate",
    headers={"Accept": "application/json"},
    json={
        "smiles": "[C@H]1O[C@@H](CO)[C@H](O)[C@@H]1O.[*{15-15}]",
        "num_molecules": 10,
        "temperature": 1.0,
        "noise": 1.0,
        "scoring": "QED",
        "filter": True,
    },
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Readiness Check

Endpoint path: /v1/health/ready

Example

curl http://127.0.0.1:8000/v1/health/ready

Example response:

true

List Models and Versions

Endpoint path: /v1/models

Example

curl http://127.0.0.1:8000/v1/models

Example response:

{"available_models":["GenMol-2.0.0"]}

API Reference

Endpoint path: /docs

Open a web browser and navigate to http://<host>:8000/docs to view the generated OpenAPI reference page.

Liveness and Metrics

For the liveness check (/v1/health/live) and runtime metrics (/v1/metrics), refer to Observability.