Overview

TimbOS API Reference

A API TimbOS expõe o pipeline semântico de áudio como serviço REST. Permite busca por linguagem natural, geração de TimbreDSL, síntese paramétrica e navegação pelo knowledge graph de timbres.

Base URL

api.timbos.io/v1

Formato

JSON · YAML · msgpack

Rate Limit

100 req/min · 10k/dia

# Exemplo mínimo de uso
curl -X GET "https://api.timbos.io/v1/search?q=bamboo+flute+melancholic" \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxx" \
  -H "Accept: application/json"

Autenticação

API Keys

Todas as requisições requerem um Bearer token no header Authorization. Chaves são geradas no dashboard.

tk_live_* — produção tk_test_* — sandbox

Authorization: Bearer tk_live_xxxxxxxxxxxx

Endpoints

Search API

GET /search Busca semântica por linguagem natural ▾

Converte uma descrição textual em embedding CLAP e retorna os samples mais próximos no espaço semântico, com scores e TimbreDSL completa.

Parâmetro	Tipo	Requerido	Descrição
q	string	required	Descrição textual do timbre (max 500 chars)
limit	integer	optional	Número de resultados (1–50, default: 10)
family	string	optional	Filtrar por família: strings, wind, brass, keyboard, percussion, electronic
include_dsl	boolean	optional	Incluir TimbreDSL completa em cada resultado (default: false)
threshold	float	optional	Score mínimo de similaridade 0.0–1.0 (default: 0.6)

200 OK

400 Error

{
  "query": "bamboo flute melancholic sunset",
  "total": 847,
  "results": [
    {
      "id": "shk_c4_001",
      "name": "Shakuhachi C4",
      "family": "wind",
      "similarity": 0.912,
      "preview_url": "https://cdn.timbos.io/samples/shk_c4_001.mp3",
      "dsl": {
        "spectral": { "brightness": 0.38, "harmonic_density": 0.60 },
        "material": { "bamboo": 0.95 },
        "emotion": { "melancholic": 0.78 }
      }
    }
  ],
  "latency_ms": 42
}

{
  "error": "invalid_query",
  "message": "Query parameter 'q' is required",
  "code": 400
}

POST /dsl/generate Gera TimbreDSL a partir de descrição ▾

Chama o pipeline multi-agente (LangGraph + Claude) para converter linguagem natural em TimbreDSL validada por schema. O endpoint mais poderoso da API.

Body Field	Tipo	Requerido	Descrição
description	string	required	Descrição textual do timbre desejado
agents	string[]	optional	Agentes a executar (default: todos os 6)
validate	boolean	optional	Validar schema Pydantic antes de retornar (default: true)

POST /v1/dsl/generate
Content-Type: application/json

{
  "description": "old bamboo flute at sunset, slightly melancholic, airy texture",
  "agents": ["acoustic", "perception", "ontology"],
  "validate": true
}

POST /dsl/synthesize Converte DSL em parâmetros de síntese

Recebe uma TimbreDSL e retorna parâmetros de síntese para Web Audio API, DDSP ou SuperCollider.

# Resposta
{
  "engine": "web_audio",
  "oscillator": { "type": "sine", "frequency": 261.63 },
  "filter": { "type": "lowpass", "frequency": 1820, "Q": 2.8 },
  "envelope": { "attack": 0.048, "decay": 0.12, "sustain": 0.82, "release": 0.34 },
  "reverb": { "room_size": 0.35, "damping": 0.60 }
}

Schema

TimbreDSL Schema

Todos os atributos numéricos são floats no range [0.0, 1.0] exceto onde indicado. O schema é validado por Pydantic v2 antes de qualquer operação de síntese ou indexação.

spectral

brightnessfloat[0,1]

harmonic_densityfloat[0,1]

noisinessfloat[0,1]

spectral_fluxfloat[0,1]

temporal

attackfloat[0,1]

decayfloat[0,1]

sustainfloat[0,1]

releasefloat[0,1]

material

woodenfloat[0,1]

metallicfloat[0,1]

bamboofloat[0,1]

glassyfloat[0,1]

electronicfloat[0,1]

emotion

lyrical · heroicfloat

melancholic · serenefloat

mysterious · eeriefloat

nostalgic · playfulfloat

aggressive · warmfloat

Playground

API Playground

Teste a API diretamente no browser. As chamadas são reais — o agente Ontology Mapper processa sua descrição e retorna a TimbreDSL canônica.

POST /v1/dsl/generate LIVE Anthropic Claude · TimbOS Ontology Mapper

Request Body

Response

// Aguardando execução...

SDKs

Client Libraries

Python

pip install timbos

JavaScript

npm install @timbos/sdk

Unity / C#

via Package Manager

# Python SDK
from timbos import TimbOSClient

client = TimbOSClient(api_key="tk_live_xxxx")

# Busca semântica
results = client.search("bamboo flute melancholic", limit=5)

# Gerar DSL
dsl = client.dsl.generate("old shakuhachi at sunset")
print(dsl.spectral.brightness)  # 0.38

# Síntese
synth_params = client.dsl.synthesize(dsl, engine="web_audio")