Embeddings

POST /v1/embeddings turns protein sequences into protein language-model embeddings (ESMC or SaProt): numeric vectors you can feed to a classifier, clustering, similarity search or any downstream model. It returns a job to poll (see Jobs). No structure prediction, no MSA.

Two kinds of vector

For every sequence you get both:

• Per-residue, shape [length, d_model]. For residue-level tasks (contact or site prediction, per-position features). The <cls>/<eos> boundary tokens are stripped, so row i is residue i.
• Pooled, shape [d_model], the per-residue vectors combined (see pool). For one vector per protein: similarity, clustering, a sequence-level classifier.

d_model depends on the model (960 for esmc-300m) and is reported in the results.

Input

Provide exactly one of these, as on Predictions.

1. sequence: a single chain

curl -s -X POST https://api.japanfold.aiand.com/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{"model":"esmc-600m","sequence":"MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQ"}'

2. sequences: a list, to embed many in one job

Each item is a bare string or an object {"sequence": "...", "id": "..."}:

curl -s -X POST https://api.japanfold.aiand.com/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{
    "model":"esmc-600m",
    "sequences":[
      {"id":"a","sequence":"MKTAYIAKQRQISFVKSHFSRQLEE"},
      {"id":"b","sequence":"GIVEQCCTSICSLYQLENYCN"}
    ]
  }'

3. input: one FASTA string

curl -s -X POST https://api.japanfold.aiand.com/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{"model":"esmc-600m","input":">a\nMKTAYIAKQRQISFVKSHFSRQLEE\n>b\nGIVEQCCTSICSLYQLENYCN"}'

Models

Set model, default esmc-600m: esmc-300m, esmc-600m, esmc-6b, saprot-650m, saprot-1.3b. Larger is a stronger representation at more compute per sequence. SaProt is trained on sequence + structure tokens and runs sequence-only here (structure tokens masked), which the 1.3B variant is explicitly trained for. See Models & limits.

Parameters

Pass a params object.

Key	Type	Default	Notes
pool	enum	mean	How per-residue vectors become the pooled vector: mean, max, or cls (the <cls> token).
format	enum	npz	npz: per-residue + pooled, one file per sequence. parquet: pooled vectors only, one table.
fast	bool	false	Higher throughput, may be slightly less precise.

curl -s -X POST https://api.japanfold.aiand.com/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{"model":"esmc-600m","sequence":"MKTAYIAK...","params":{"pool":"mean","format":"npz"}}'

Results

Once results_ready is true, GET /v1/jobs/{id}/results carries kind: "embed", the model, pool, format, d_model, a sequences list ({id, length, file} per input) and an artifacts list of download URLs.

• npz (default): one <id>.npz per sequence with arrays per_residue [length, d_model], pooled [d_model] and sequence.
• parquet: a single embeddings.parquet holding the pooled matrix, one row per sequence. Per-residue vectors are ragged, so they are not in the table; use npz for those.

Download individual files from their artifact url, or the whole set from GET /v1/jobs/{id}/archive.

End to end (Python)

import io, time, httpx, numpy as np

BASE = "https://api.japanfold.aiand.com"
job = httpx.post(f"{BASE}/v1/embeddings",
                 json={"model": "esmc-600m",
                       "sequence": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQ"}).json()
while job["status"] not in ("succeeded", "failed", "canceled"):
    time.sleep(3)
    job = httpx.get(f"{BASE}/v1/jobs/{job['id']}").json()

res = httpx.get(f"{BASE}/v1/jobs/{job['id']}/results").json()
url = BASE + res["artifacts"][0]["url"]
data = np.load(io.BytesIO(httpx.get(url).content))
print(data["per_residue"].shape, data["pooled"].shape)  # (L, d_model) (d_model,)

With the JapanFold skill installed, ask instead: "Embed these sequences with ESMC-600M and save the pooled vectors."

Embed jobs accept the same Prefer: wait[=seconds] and Idempotency-Key headers as predictions (see Predictions).

Limits

At most 50 sequences per submission and 2000 residues per sequence (1968 for esmc-6b), higher than the folding cap because embeddings run the language model only. Over a cap you get 400, at capacity 429. See Models & limits and Errors.