Inovacc Desenvolvedores

Referência da API

Embeddings de IA

Transforme texto em vetores para busca e similaridade.

URL base https://ai.inovacc.dev

Visão geral

Os Embeddings de IA transformam texto em vetores: listas de números cuja distância entre si acompanha o significado do texto. Dois trechos sobre o mesmo assunto ficam próximos mesmo quando não compartilham nenhuma palavra. O endpoint, POST /v1/embeddings, fala o formato de comunicação de embeddings da OpenAI, então um cliente da OpenAI já existente pode chamá-lo com a URL base https://ai.inovacc.dev/v1 e dois cabeçalhos extras.

O problema que ele resolve é a comparação semântica dentro dos seus próprios sistemas. Com vetores você pode buscar por significado, agrupar itens semelhantes, encontrar quase duplicatas ou direcionar uma mensagem para a categoria mais próxima, usando o banco de dados ou o índice que você já opera.

Use os Embeddings de IA quando você guarda os vetores. Quando preferir que a Inovacc os guarde, faça a busca e devolva os trechos correspondentes, use o Banco de Dados Vetorial gerenciado de Conhecimento e busca vetorial, que gera os embeddings dos seus documentos por você. Quando precisar de texto gerado em vez de vetores, use o Chat com IA.

Conceitos

Rotas. Como no chat, você nunca nomeia um modelo. Sua organização recebe rotas de embeddings, ids opacos configurados pela Inovacc. GET /v1/models as lista: uma entrada cujo endpoint é /v1/embeddings é uma rota de embeddings. Envie o id dela como model, ou envie "auto" (ou nenhum model) para usar a rota padrão da sua organização. Uma rota atende um único endpoint; uma rota de chat chamada aqui é recusada.

Entrada. input é uma string não vazia, ou um array de strings; dentro de um array, uma string vazia é aceita. A resposta traz um vetor por entrada, em data[], cada um com o index da entrada a que pertence.

Os vetores de uma rota pertencem juntos. Um vetor só é comparável com vetores produzidos pela mesma rota. Guarde o id da rota junto de cada vetor que você armazena, e gere os embeddings dos seus documentos e das suas consultas com a mesma rota.

Campos opcionais. encoding_format e dimensions são repassados ao modelo quando o modelo da rota os suporta e ignorados caso contrário. user é aceito como string e substituído, antes de sair da Inovacc, por um valor derivado da sua organização, de modo que duas organizações que enviam o mesmo valor nunca colidem.

Uso. O usage da resposta contém prompt_tokens e total_tokens. Este endpoint não traz cabeçalhos x-usage-*; a rota que respondeu está em x-route-id.

Como funciona

Toda chamada leva Authorization: Bearer <key> e um X-Operation-Id. Sua organização vem da chave. O serviço verifica o id de operação e a chave, depois se aquele id de operação já foi usado, e então o corpo: apenas model, input, encoding_format, dimensions e user são aceitos, e qualquer outro campo é recusado pelo nome. Ele resolve a rota, verifica se a rota atende embeddings, valida input, estima o tamanho da entrada (um quarto dos caracteres de cada string de entrada) contra o limite por requisição da sua organização e reserva a chamada contra as cotas da sua organização. Só então o modelo é chamado.

A resposta é {"object":"list","data":[{"object":"embedding","index":0,"embedding":[...]}],"model":"<route id>","usage":{...}}. model é sempre o id da rota.

Não há transmissão. Uma resposta bem-sucedida é armazenada por 24 horas sob o seu id de operação: o mesmo id enviado de novo devolve os mesmos vetores com x-idempotent-replay: true, sem uma segunda chamada nem cobrança. Um erro nunca é armazenado, então uma chamada que falhou pode ser repetida com o mesmo id. O que é medido são os tokens de entrada.

Primeiros passos

Você precisa de uma chave de API e de uma rota de embeddings habilitada para a sua organização (Autenticação).

  1. Encontre a sua rota de embeddings. Chame GET /v1/models e escolha uma entrada cujo endpoint seja /v1/embeddings.
  2. Gere embeddings de dois trechos. Chame POST /v1/embeddings com essa rota como model, um array input com duas strings e um X-Operation-Id novo (veja os exemplos). A resposta tem duas entradas em data, com index 0 e 1, e model é o id da sua rota.
  3. Compare-os. Calcule a similaridade de cosseno dos dois vetores no seu código. Gere o embedding de um terceiro trecho sobre outro assunto e compare de novo: a pontuação dele contra o primeiro é menor.
  4. Repita. Envie o passo 2 novamente com o mesmo id de operação; os vetores são idênticos e a resposta traz x-idempotent-replay: true.

Casos de uso

Busca no seu próprio banco de dados. Um catálogo de produtos guarda um vetor por descrição de produto no banco de dados que já usa. A pergunta de um comprador tem o embedding gerado com a mesma rota no momento da consulta, e os produtos mais próximos são exibidos, inclusive aqueles cuja descrição usa palavras diferentes.

Detecção de quase duplicatas. Um sistema de chamados gera o embedding de cada novo chamado e o compara com os abertos; uma pontuação acima de um limiar que você calibra vincula o chamado ao caso existente em vez de abrir um segundo.

Direcionamento por similaridade. Um pequeno conjunto de mensagens de exemplo por equipe tem o embedding gerado uma única vez. Cada mensagem recebida tem o embedding gerado e é enviada à equipe cujos exemplos estão mais próximos, sem nenhuma chamada de modelo por mensagem além do embedding.

Limites e preços

LimiteValor
Corpo da requisição1 MiB por padrão; sua organização pode ser configurada entre 1 KiB e 20 MiB
Tokens de entrada por requisiçãoo limite da sua organização (400 input_too_large acima dele)
Tempo até a primeira resposta do modelo60 segundos
Resposta armazenada para repetição24 horas
Requisições, tokens, custo, simultaneidade, orçamentos diáriosconforme definido para a sua organização

Preços: sob consulta. A unidade de preço é tokens.

Erros

StatusCódigoO que significa e o que fazer
400missing_operation_id, invalid_operation_idEnvie um X-Operation-Id válido.
400unsupported_fieldUm campo diferente de model, input, encoding_format, dimensions, user; remova-o.
400invalid_bodyJSON malformado, input com formato errado, ou um user que não é string.
400model_not_allowedmodel não é um id de rota válido.
400input_too_largeA entrada excede o seu limite por requisição; divida-a em várias chamadas.
401missing_credentials, invalid_credentialsEnvie uma chave válida.
403route_forbiddenA rota não é sua, está desativada, ou não atende embeddings.
403key_disabled, organization_disabledVerifique a chave.
409operation_in_progressEsse id de operação ainda está em execução; aguarde e tente novamente.
413request_too_largeO corpo excede o seu limite de tamanho.
429rate_limited, budget_exhaustedAguarde os segundos de Retry-After.
429quota_exceeded, concurrency_limitedUma cota se esgotou; sem Retry-After.
502, 503, 504upstream_error, service_unavailable, timeout_errorTente novamente com o mesmo id de operação e espera crescente.

Veja Erros para o envelope.

Boas práticas

  • Agrupe as entradas: envie muitos trechos em um único array input, dentro dos seus limites de tamanho e de tokens, em vez de uma chamada por trecho.
  • Guarde o id da rota junto com o vetor, e gere novamente todos os embeddings se trocar de rota: vetores de duas rotas não são comparáveis.
  • Divida documentos longos em trechos de alguns parágrafos antes de gerar os embeddings; um único vetor para um documento inteiro dilui o seu significado.
  • Derive o id de operação do conteúdo (por exemplo, um hash do lote) para que uma tarefa reiniciada repita a resposta em vez de pagar de novo.
  • Repita 502, 503 e 504 com o mesmo id de operação; aguarde Retry-After em 429 rate_limited.
  • Calibre os limiares com os seus próprios dados: as pontuações de similaridade são relativas, não probabilidades.

Autenticação

Toda chamada leva a sua chave; a sua organização vem dela. Veja o guia de autenticação.

CabeçalhoAuthorizationBearer <chave de API>
CabeçalhoX-Operation-Idum id único que você escolhe, em toda chamada exceto GET

Endpoints

POST /v1/embeddings

Exemplo

Linguagem

⋮
POST /v1/embeddingsExemplo

cURL

curl -X POST "https://ai.inovacc.dev/v1/embeddings" \
  -H "Authorization: Bearer $INOVACC_API_KEY" \
  -H "X-Operation-Id: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "input": [
    "first passage",
    "second passage"
  ],
  "model": "r-embed"
}'

TypeScript

import crypto from "node:crypto";

const body: Record<string, unknown> = {
  "input": [
    "first passage",
    "second passage"
  ],
  "model": "r-embed"
};

const url = "https://ai.inovacc.dev/v1/embeddings";

const response = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INOVACC_API_KEY}`,
    "X-Operation-Id": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});

console.log(response.status, await response.text());

Python

import json
import os
import urllib.request
import uuid

body = {
    "input": [
        "first passage",
        "second passage",
    ],
    "model": "r-embed",
}

request = urllib.request.Request(
    "https://ai.inovacc.dev/v1/embeddings",
    data=json.dumps(body).encode(),
    method="POST",
    headers={
        "User-Agent": "inovacc-python-sample",
        "Authorization": "Bearer " + os.environ["INOVACC_API_KEY"],
        "X-Operation-Id": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
)

with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Go

package main

import (
	"crypto/rand"
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

const url = "https://ai.inovacc.dev/v1/embeddings"

const body = `{
  "input": [
    "first passage",
    "second passage"
  ],
  "model": "r-embed"
}`

// newUUID returns a random (version 4) UUID, from the standard library alone.
func newUUID() string {
	b := make([]byte, 16)
	if _, err := rand.Read(b); err != nil {
		panic(err)
	}
	b[6] = b[6]&0x0f | 0x40
	b[8] = b[8]&0x3f | 0x80
	return fmt.Sprintf("%x-%x-%x-%x-%x", b[0:4], b[4:6], b[6:8], b[8:10], b[10:])
}

func main() {
	req, err := http.NewRequest("POST", url, strings.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("INOVACC_API_KEY"))
	req.Header.Set("X-Operation-Id", newUUID())
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(res.Status, string(out))
}

Rust

// Cargo.toml: reqwest = { version = "0.12", features = ["blocking", "json"] }
// Cargo.toml: serde_json = "1"
// Cargo.toml: uuid = { version = "1", features = ["v4"] }

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("INOVACC_API_KEY")?;
    let body = serde_json::json!({
        "input": [
            "first passage",
            "second passage"
        ],
        "model": "r-embed"
    });
    let response = reqwest::blocking::Client::new()
        .post("https://ai.inovacc.dev/v1/embeddings")
        .bearer_auth(api_key)
        .header("X-Operation-Id", uuid::Uuid::new_v4().to_string())
        .json(&body)
        .send()?;
    println!("{} {}", response.status(), response.text()?);
    Ok(())
}

JavaScript

import crypto from "node:crypto";

const body = {
  "input": [
    "first passage",
    "second passage"
  ],
  "model": "r-embed"
};

const url = "https://ai.inovacc.dev/v1/embeddings";

const response = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INOVACC_API_KEY}`,
    "X-Operation-Id": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});

console.log(response.status, await response.text());

PHP

<?php

$body = <<<'JSON'
{
  "input": [
    "first passage",
    "second passage"
  ],
  "model": "r-embed"
}
JSON;

function uuid4(): string
{
    $bytes = random_bytes(16);
    $bytes[6] = chr(ord($bytes[6]) & 0x0f | 0x40);
    $bytes[8] = chr(ord($bytes[8]) & 0x3f | 0x80);
    return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($bytes), 4));
}

$curl = curl_init('https://ai.inovacc.dev/v1/embeddings');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INOVACC_API_KEY'),
        'X-Operation-Id: ' . uuid4(),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($curl);
echo curl_getinfo($curl, CURLINFO_HTTP_CODE), ' ', $response, "\n";
curl_close($curl);

Ruby

require "net/http"
require "securerandom"
require "uri"

uri = URI('https://ai.inovacc.dev/v1/embeddings')
body = <<~'JSON'
{
  "input": [
    "first passage",
    "second passage"
  ],
  "model": "r-embed"
}
JSON

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch('INOVACC_API_KEY')}"
request["X-Operation-Id"] = SecureRandom.uuid
request["Content-Type"] = "application/json"
request.body = body

response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts "#{response.code} #{response.body}"

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.UUID;

public class Main {
    public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("INOVACC_API_KEY");
        String body = "{" +
                "\"input\": [" +
                "\"first passage\"," +
                "\"second passage\"" +
                "]," +
                "\"model\": \"r-embed\"" +
                "}";

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://ai.inovacc.dev/v1/embeddings"))
                .header("Authorization", "Bearer " + apiKey)
                .header("X-Operation-Id", UUID.randomUUID().toString())
                .header("Content-Type", "application/json")
                .method("POST", HttpRequest.BodyPublishers.ofString(body))
                .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
                .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

C#

using System.Text;

var body = "{" +
    "\"input\": [" +
    "\"first passage\"," +
    "\"second passage\"" +
    "]," +
    "\"model\": \"r-embed\"" +
    "}";

var url = "https://ai.inovacc.dev/v1/embeddings";
var apiKey = Environment.GetEnvironmentVariable("INOVACC_API_KEY");

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, url);
request.Headers.Add("Authorization", $"Bearer {apiKey}");
request.Headers.Add("X-Operation-Id", Guid.NewGuid().ToString());
request.Content = new StringContent(body, Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

Kotlin

import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
import java.util.UUID

fun main() {
    val apiKey = System.getenv("INOVACC_API_KEY")
    val body = "{" +
        "\"input\": [" +
        "\"first passage\"," +
        "\"second passage\"" +
        "]," +
        "\"model\": \"r-embed\"" +
        "}"

    val request = HttpRequest.newBuilder()
        .uri(URI.create("https://ai.inovacc.dev/v1/embeddings"))
        .header("Authorization", "Bearer " + apiKey)
        .header("X-Operation-Id", UUID.randomUUID().toString())
        .header("Content-Type", "application/json")
        .method("POST", HttpRequest.BodyPublishers.ofString(body))
        .build()

    val response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString())
    println("${response.statusCode()} ${response.body()}")
}

Swift

import Foundation
#if canImport(FoundationNetworking)
import FoundationNetworking
#endif

let body = #"""
{
  "input": [
    "first passage",
    "second passage"
  ],
  "model": "r-embed"
}
"""#

let apiKey = ProcessInfo.processInfo.environment["INOVACC_API_KEY"] ?? ""

let url = URL(string: "https://ai.inovacc.dev/v1/embeddings")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
request.setValue(UUID().uuidString, forHTTPHeaderField: "X-Operation-Id")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = Data(body.utf8)

let (data, response) = try await URLSession.shared.data(for: request)
let status = (response as? HTTPURLResponse)?.statusCode ?? 0
print(status, String(decoding: data, as: UTF8.self))
Detalhes da fonte

Entrada do catálogo

Id
identity/component-taxonomy/capabilities#ai.embeddings
Repositório
identity
Caminho
contracts/component-taxonomy/catalog/capabilities.json
Commit
08ef3cd75d82

Exemplo

Id
identity/component-taxonomy/quickstart#ai.embeddings
Repositório
identity
Caminho
contracts/component-taxonomy/catalog/capabilities.json
Commit
08ef3cd75d82
Atualizado em 2026-10-10.