POST /v1/embeddings

Endpoint OpenAI-compatible pra gerar embeddings vetoriais. Útil pra busca semântica, RAG (retrieval-augmented generation) e clustering de textos em pt-BR.

Autenticação

http

Authorization: Bearer sk-tokia-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Mesma key gerada em /dashboard/keys. Cobertura por modelo segue a lista permitida na key — adicione embeddings na criação ou edite a key existente.

Request body

Campo	Tipo	Obrigatório	Descrição
`model`	string	sim	ID do modelo (ex: `openrouter/openai/text-embedding-3-small`).
`input`	string \| string[]	sim	Texto único OU array de textos (batch).
`encoding_format`	string	não	`float` (default) ou `base64`.
`dimensions`	number	não	Trunca o vetor (apenas modelos OpenAI v3 suportam).

Exemplo cURL

bash

curl https://api.usetokia.com/v1/embeddings \
  -H "Authorization: Bearer $TOKIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openrouter/openai/text-embedding-3-small",
    "input": ["Tokia é uma plataforma SaaS de IA brasileira."]
  }'

Exemplo Python (SDK OpenAI)

python

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKIA_KEY"],
    base_url="https://api.usetokia.com/v1",
)

result = client.embeddings.create(
    model="openrouter/openai/text-embedding-3-small",
    input=["primeiro texto", "segundo texto"],
)
for item in result.data:
    print(item.index, len(item.embedding))

Response

json

{
  "object": "list",
  "data": [
    { "object": "embedding", "embedding": [0.0234, -0.0019, ...], "index": 0 }
  ],
  "model": "text-embedding-3-small",
  "usage": { "prompt_tokens": 12, "total_tokens": 12 }
}

Como o custo aparece

Embeddings cobram por token (sem completion). Custo Tokia = upstream USD × FX BCB × markup do modelo (DR-009/010). Acompanhe em /dashboard/usage.

Códigos de erro

Tabela completa em /docs/api/errors. Erros comuns:

HTTP	code	Causa
400	`invalid_request`	input vazio ou modelo de chat passado por engano.
401	`authentication_failed`	Key não tem o modelo de embedding na lista permitida.
404	`model_not_found`	ID do modelo inexistente — veja /docs/models.