Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.synthesize.bio/llms.txt

Use this file to discover all available pages before exploring further.

pysynthbio is a Python package for the Synthesize Bio API. It lets researchers easily access AI-generated transcriptomic data across modalities including bulk and single-cell RNA-seq. To generate datasets without code, use the web platform.

​
Authentication

​
Get your API key

Visit the API keys page to generate a key. Click + Create API Key, then Create Key, and copy your key. There are several ways to make pysynthbio aware of your token. 
import pysynthbio

# Opens a browser to the token creation page and prompts for input
pysynthbio.set_synthesize_token(use_keyring=True)
With use_keyring=True, the token persists across sessions; with use_keyring=False, it’s only set for the current session. Keyring support is included by default in pysynthbio 2.2.1 and later.

​
Available model types

Synthesize Bio provides several model types for different use cases.

​
Baseline models

Generate synthetic gene expression data from metadata alone. Describe the biological conditions and the model generates realistic expression profiles.
  • gem-1-bulk: Bulk RNA-seq baseline model
  • gem-1-sc: Single-cell RNA-seq baseline model
See Baseline models for detailed usage.

​
Reference conditioning models

Generate expression data conditioned on a real reference sample. This lets you anchor to an existing expression profile while applying perturbations or modifications.
  • gem-1-bulk_reference-conditioning: Bulk RNA-seq reference conditioning model
  • gem-1-sc_reference-conditioning: Single-cell RNA-seq reference conditioning model
See Reference conditioning for detailed usage.

​
Metadata prediction models

Infer metadata from observed expression data. Given a gene expression profile, predict likely biological characteristics such as cell type, tissue, or disease state.
  • gem-1-bulk_predict-metadata: Bulk RNA-seq metadata prediction model
  • gem-1-sc_predict-metadata: Single-cell RNA-seq metadata prediction model
See Metadata prediction for detailed usage.
Only baseline models are available to all users. Check programmatically with list_models(). Contact support@synthesize.bio if you have questions.

​
Listing available models

import pysynthbio

models = pysynthbio.list_models()
print(models)

​
Exploring available metadata

Each model accepts a specific set of metadata fields with defined vocabularies (valid ontology IDs, cell lines, tissues, etc.). Browse and download these vocabularies at app.synthesize.bio/docs/vocab. See Available metadata for more details.

​
Quick start

A minimal example using a baseline model: 
import pysynthbio

# Get an example query structure
query = pysynthbio.get_example_query(model_id="gem-1-bulk")["example_query"]

# Submit the query and get results
result = pysynthbio.predict_query(query, model_id="gem-1-bulk")

# Access the results
metadata = result["metadata"]
expression = result["expression"]
For more detailed examples and advanced usage, see the model-specific documentation linked above.

​
Security notes

  • The API token provides full access to your Synthesize Bio account.
  • When using use_keyring=True, your token is stored securely in your system’s credential manager.
  • For production environments, prefer environment variables or a secrets management tool.

​
Cleanup

When you’re done using the API, you can clear the token from your environment: 
# Clear from current session only
pysynthbio.clear_synthesize_token()

# Clear from both session and system keyring
pysynthbio.clear_synthesize_token(remove_from_keyring=True)

​
Rate limits

Free usage of Synthesize Bio is limited. If you exceed the limit, the API returns an error explaining it. For higher limits, contact support@synthesize.bio.

​
Troubleshooting

​
Keychain access on Mac

If you get this error on macOS when using use_keyring=True: 
<stdin>:1: UserWarning: Failed to store token in keyring:
Can't store password on keychain: (-25244, 'Unknown Error')
Your IDE or terminal does not have access to Keychain. Open System Preferences -> Security & Privacy -> Privacy -> Full Disk Access and add the terminal or IDE you’re working from.