API de Embeddings

Use embeddings da CometAPI quando seu app precisar de vetores para busca semântica, clustering, recomendações ou retrieval. Envie texto para /v1/embeddings, armazene o vetor retornado e faça buscas nele com seu banco de dados vetorial.

Criar um embedding

Use um model ID com suporte a embedding da página Models ou do diretório de modelos. Os exemplos abaixo chamam a API de Embeddings compatível com OpenAI.

Estes exemplos usam o placeholder your-embedding-model-id. Substitua-o por um model ID de embedding disponível na página Models ou no diretório de modelos antes de executar a requisição.

Abra Create embeddings para usar o playground e o schema do endpoint.

import os
import requests

response = requests.post(
    "https://api.cometapi.com/v1/embeddings",
    headers={
        "Authorization": "Bearer " + os.environ["COMETAPI_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "model": "your-embedding-model-id",
        "input": "CometAPI lets developers use many model providers.",
    },
    timeout=30,
)

response.raise_for_status()
result = response.json()
print(len(result["data"][0]["embedding"]))

const response = await fetch("https://api.cometapi.com/v1/embeddings", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "your-embedding-model-id",
    input: "CometAPI lets developers use many model providers.",
  }),
});

if (!response.ok) {
  throw new Error(await response.text());
}

const result = await response.json();
console.log(result.data[0].embedding.length);

curl https://api.cometapi.com/v1/embeddings \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-embedding-model-id",
    "input": "CometAPI lets developers use many model providers."
  }'

Exemplo de resposta

Uma resposta bem-sucedida pode ser assim. A resposta inclui um vetor para cada item de entrada; o vetor abaixo foi encurtado para facilitar a leitura:

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        -0.0021,
        -0.0491,
        0.0209
      ]
    }
  ],
  "model": "your-embedding-model-id",
  "usage": {
    "prompt_tokens": 10,
    "total_tokens": 10
  }
}

Entrada em lote

Envie um array de strings quando quiser vários vetores em uma única requisição:

cURL

curl https://api.cometapi.com/v1/embeddings \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-embedding-model-id",
    "input": [
      "Create an API key",
      "Change the base URL",
      "Retry after a rate limit"
    ]
  }'

Exemplos de registros de modelo

Este exemplo de resposta do catálogo de modelos mostra o envelope de /api/models e o formato de um registro de modelo de embedding compatível com OpenAI. Alguns registros de embedding usam model_type vazio; escolha um modelo de embedding pelo ID e pelo suporte ao endpoint, em vez de depender apenas desse campo.

cURL

curl https://api.cometapi.com/api/models

{
  "success": true,
  "page": 1,
  "page_size": 20,
  "total": 302,
  "data": [
    {
      "created": 1757904564,
      "id": "your-embedding-model-id",
      "code": "your-embedding-model-id",
      "provider": "ExampleProvider",
      "provider_code": "example",
      "name": "Example embedding model",
      "model_type": "embedding",
      "features": [
        "text-embedding"
      ],
      "endpoints": [
        "openai"
      ],
      "pricing": {
        "currency": "USD / M Tokens",
        "input": 0.1,
        "output": null,
        "per_request": null,
        "per_second": null
      }
    }
  ]
}

Erros comuns

Input too long

Divida documentos longos em partes antes de gerar embeddings.

Wrong model type

Escolha um modelo com capacidade de embedding no diretório de modelos.

Vector dimensions mismatch

Mantenha o mesmo modelo e as mesmas dimensões para um índice vetorial.

Missing API key

Envie Authorization: Bearer $COMETAPI_KEY.

Códigos de erro e estratégia de retry

400

Não tente novamente até que a entrada, o model ID ou a configuração de dimensões seja corrigida.

401

Não tente novamente até que a chave de API esteja presente e seja válida.

404

Verifique a URL base, o caminho e o model ID antes de tentar novamente.

429

Tente novamente com exponential backoff e reduza o tamanho do lote ou a concorrência.

500 or 503

Tente novamente com backoff para erros transitórios do provedor ou do serviço.

Para padrões de implementação, consulte Error codes and retry strategy e Rate limits and concurrency.

Preços e diretório de modelos

Models page

Leia como a CometAPI expõe model IDs na documentação.

Model directory

Navegue pela disponibilidade e pelas capacidades dos modelos.

Pricing

Verifique os preços antes de chamar um modelo.

Moderação de conteúdo

Chaves de API

Criar um embedding

Exemplo de resposta

Entrada em lote

Exemplos de registros de modelo

Erros comuns

Códigos de erro e estratégia de retry

Preços e diretório de modelos

Models page

Model directory

Pricing

​Criar um embedding

​Exemplo de resposta

​Entrada em lote

​Exemplos de registros de modelo

​Erros comuns

​Códigos de erro e estratégia de retry

​Preços e diretório de modelos

Models page

Model directory

Pricing

Criar um embedding

Exemplo de resposta

Entrada em lote

Exemplos de registros de modelo

Erros comuns

Códigos de erro e estratégia de retry

Preços e diretório de modelos