Model Constraints
Some models have rules about their input — a max audio length, a fixed image size, or "exactly one face per query". If you break one, you get a clear error. Here's what to watch for per family.
Audio Models (CLAP)
| Constraint | Value | Notes |
|---|---|---|
| Max duration | 10 minutes (600 seconds) | Longer clips will error with AudioTooLongError |
| Sample rate | 48 kHz | Audio is automatically resampled |
| Max samples | 28,800,000 | 48,000 Hz × 600 seconds |
| Chunk size | 10 seconds | Long audio is automatically split into overlapping chunks |
| Chunk overlap | 1 second | Provides temporal continuity between chunks |
| Embedding mode | OneToMany | Returns one embedding per chunk with temporal metadata |
| Preprocessing | Required | NoPreprocessing not supported - always use ModelPreprocessing |
Audio chunking behavior:
- Audio ≤10 seconds: Returns 1 embedding
- Audio >10 seconds: Automatically chunked into 10-second segments with 1-second overlap
- Each chunk embedding includes metadata:
chunk_start_sec,chunk_end_sec,chunk_duration_sec,total_chunks,audio_total_duration_sec
Face Models (Buffalo_L, SFace+YuNet)
| Constraint | Value | Notes |
|---|---|---|
| Input size | 640x640 px | Images are resized internally |
| Face alignment | 112x112 px | Standard ArcFace alignment |
| Embedding mode | OneToMany | Returns one embedding per detected face |
| Preprocessing | Required | NoPreprocessing not supported |
| Query constraint | Single face | Query images must contain exactly 1 face |
Text & Code Models
Every text-based model, including the code model, counts tokens using its own
tokenizer, not characters or words, and each has a fixed maximum input length.
Input over that length is rejected outright with a TokenExceededError
(OutOfRange). Nothing is silently truncated.
| Model | string name | Max input |
|---|---|---|
| ALL-MiniLM-L6-v2 | all-minilm-l6-v2 | 256 tokens |
| ALL-MiniLM-L12-v2 | all-minilm-l12-v2 | 256 tokens |
| BGE-Base-EN-v1.5 | bge-base-en-v1.5 | 512 tokens |
| BGE-Large-EN-v1.5 | bge-large-en-v1.5 | 512 tokens |
| CLIP ViT-B/32 (text) | clip-vit-b32-text | 77 tokens |
| CLAP (text) | clap-text | 512 tokens |
| Jina Code v2 | jina-embeddings-v2-base-code | 8192 tokens |
Batched Request Behavior
When several inputs are sent in one Set call, they're
processed together as a batch, and every input in that batch is padded up to
match the length of the longest one in it. A batch combining one near-limit
input with several short ones costs close to what it would cost if every
input in the batch were near-limit (not the sum of each input's individual
cost). This is standard behavior for transformer-based embedding models,
not an Ahnlich-specific limitation, but it has a real cost implication
worth planning around.
For workloads that chunk long text before indexing (source files, documents), this matters once chunking is working and you start grouping chunks into batches:
- Keep chunks of similar size in the same batch; avoid mixing a near-limit chunk in with much smaller ones.
- Give chunks close to the model's max token limit their own batch rather than batching them with anything else.
See Token Limit Exceeded for a worked example of chunking and batching long text.
Cross-modal pairs
Certain text and media encoders share a dimension so you can search across modalities — see Cross-modal pairs on the Models page.