# CentopeIA — documentação completa

> Acesso a GPT (OpenAI), Claude (Anthropic), modelos 3D e mídia (imagem, vídeo, áudio) com uma única chave, usando os SDKs oficiais de cada provedor.

## Essencial

- Uma chave CentopeIA (`sk-ctp-...`) funciona com os SDKs oficiais da OpenAI, da Anthropic e do Replicate, e com a API de modelos 3D. Use a chave e o endereço base da Centopeia. Confira os parâmetros e limites publicados para o modelo antes de integrar.
- Endereço base para GPT (SDK da OpenAI): https://centopeia.io/openai/v1
- Endereço base para Claude (SDK da Anthropic): https://centopeia.io/anthropic (o SDK completa `/v1`; em HTTP direto use https://centopeia.io/anthropic/v1)
- Endereço base para modelos 3D a partir de imagens (API compatível com a da Meshy): https://centopeia.io/meshy/openapi/v1
- Endereço base para imagem, vídeo, áudio e modelos abertos (SDK do Replicate): https://centopeia.io/replicate/v1 (no SDK Python use `base_url="https://centopeia.io/replicate"`)
- Mídia e 3D são tarefas assíncronas: crie, guarde o id e consulte até terminar. Baixe os resultados logo (1 hora para mídia, 3 dias para 3D).
- Guarde a chave na variável de ambiente `CENTOPEIA_API_KEY`. Nunca a coloque em código de navegador ou app mobile: chame a API a partir do servidor.
- Autenticação: `Authorization: Bearer <chave>` ou `x-api-key: <chave>`.
- Sempre informe o limite de saída: `max_completion_tokens` no Chat Completions, `max_output_tokens` na Responses API e `max_tokens` no Claude. Chamadas de geração de texto exigem limite de saída.
- Em streaming do Chat Completions, o último pedaço traz só o consumo, com `choices` vazio: confira antes de ler `choices[0]`.
- Modelos de exemplo: `gpt-5.5` (GPT) e `claude-sonnet-5-5` (Claude). Liste os disponíveis em `GET /models`.

## Início rápido

Instalação:

```bash
pip install openai anthropic replicate requests
npm install openai @anthropic-ai/sdk replicate
```

Variável de ambiente:

```bash
CENTOPEIA_API_KEY=sk-ctp-...
```

### GPT (OpenAI)

Python:

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CENTOPEIA_API_KEY"],
    base_url="https://centopeia.io/openai/v1",
)

resposta = client.chat.completions.create(
    model="gpt-5.5",
    max_completion_tokens=500,
    messages=[{"role": "user", "content": "Diga olá em uma frase."}],
)
print(resposta.choices[0].message.content)
```

Node.js:

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CENTOPEIA_API_KEY,
  baseURL: "https://centopeia.io/openai/v1",
});

const resposta = await client.chat.completions.create({
  model: "gpt-5.5",
  max_completion_tokens: 500,
  messages: [{ role: "user", content: "Diga olá em uma frase." }],
});
console.log(resposta.choices[0].message.content);
```

cURL:

```bash
curl https://centopeia.io/openai/v1/chat/completions \
  -H "Authorization: Bearer $CENTOPEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "max_completion_tokens": 500,
    "messages": [{"role": "user", "content": "Diga olá em uma frase."}]
  }'
```

### Claude (Anthropic)

Python:

```python
import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["CENTOPEIA_API_KEY"],
    base_url="https://centopeia.io/anthropic",
)

mensagem = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Diga olá em uma frase."}],
)
print(mensagem.content[0].text)
```

Node.js:

```javascript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.CENTOPEIA_API_KEY,
  baseURL: "https://centopeia.io/anthropic",
});

const mensagem = await client.messages.create({
  model: "claude-sonnet-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Diga olá em uma frase." }],
});
console.log(mensagem.content[0].text);
```

cURL:

```bash
curl https://centopeia.io/anthropic/v1/messages \
  -H "x-api-key: $CENTOPEIA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Diga olá em uma frase."}]
  }'
```

## Integração só com variáveis de ambiente

Os SDKs oficiais leem a chave e o endereço base do ambiente, sem mudar o código:

```bash
# Os SDKs oficiais leem estas variáveis sozinhos
OPENAI_API_KEY=sk-ctp-...
OPENAI_BASE_URL=https://centopeia.io/openai/v1

ANTHROPIC_API_KEY=sk-ctp-...
ANTHROPIC_BASE_URL=https://centopeia.io/anthropic
```

Python:

```python
from openai import OpenAI
from anthropic import Anthropic

gpt = OpenAI()        # já aponta para a CentopeIA
claude = Anthropic()  # idem
```

Node.js:

```javascript
import OpenAI from "openai";
import Anthropic from "@anthropic-ai/sdk";

const gpt = new OpenAI();        // já aponta para a CentopeIA
const claude = new Anthropic();  // idem
```

## GPT (OpenAI)

### Responses API

Python:

```python
resposta = client.responses.create(
    model="gpt-5.5",
    input="Explique o que é uma API em duas frases.",
    max_output_tokens=500,
)
print(resposta.output_text)
```

Node.js:

```javascript
const resposta = await client.responses.create({
  model: "gpt-5.5",
  input: "Explique o que é uma API em duas frases.",
  max_output_tokens: 500,
});
console.log(resposta.output_text);
```

cURL:

```bash
curl https://centopeia.io/openai/v1/responses \
  -H "Authorization: Bearer $CENTOPEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Explique o que é uma API em duas frases.",
    "max_output_tokens": 500
  }'
```

### Streaming

Python:

```python
stream = client.chat.completions.create(
    model="gpt-5.5",
    max_completion_tokens=500,
    messages=[{"role": "user", "content": "Conte uma história curta."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices:  # o último pedaço traz apenas o consumo
        print(chunk.choices[0].delta.content or "", end="", flush=True)
```

Node.js:

```javascript
const stream = await client.chat.completions.create({
  model: "gpt-5.5",
  max_completion_tokens: 500,
  messages: [{ role: "user", content: "Conte uma história curta." }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

cURL:

```bash
curl -N https://centopeia.io/openai/v1/chat/completions \
  -H "Authorization: Bearer $CENTOPEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "max_completion_tokens": 500,
    "stream": true,
    "messages": [{"role": "user", "content": "Conte uma história curta."}]
  }'
```

### Embeddings

Python:

```python
resultado = client.embeddings.create(
    model="text-embedding-3-small",
    input=["CentopeIA", "IA em reais"],
)
vetor = resultado.data[0].embedding
print(len(vetor))
```

Node.js:

```javascript
const resultado = await client.embeddings.create({
  model: "text-embedding-3-small",
  input: ["CentopeIA", "IA em reais"],
});
console.log(resultado.data[0].embedding.length);
```

cURL:

```bash
curl https://centopeia.io/openai/v1/embeddings \
  -H "Authorization: Bearer $CENTOPEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "text-embedding-3-small", "input": ["CentopeIA", "IA em reais"]}'
```

### Geração de imagens

Modelo recomendado: `gpt-image-2.5-sunburst` (máximo detalhe). Alternativas: `gpt-image-2.5-flare` (mais rápido) e `gpt-image-2`.
A imagem volta em base64 (`data[0].b64_json`).

Regras de tamanho para `gpt-image-2` e `gpt-image-2.5-*`: largura e altura múltiplas de 16, lado maior de até 3840 px, proporção de até 3:1 e entre cerca de 0,65 e 8,3 megapixels. `1600x900` é recusado (900 não é múltiplo de 16); para 16:9 use `1536x864` ou `2560x1440`.
Qualidade: `low`, `medium`, `high`, `xhigh`, `max` (`xhigh` e `max` só na geração 2.5).
Sempre informe `size` e `quality`.

| Tamanho | Formato | Uso |
| --- | --- | --- |
| `1024x1024` | Quadrado | Posts e avatares |
| `1536x864` | 16:9 | Banners e capas |
| `864x1536` | 9:16 | Stories e telas de celular |
| `1536x1024` | 3:2 | Fotografia |
| `3840x2160` | 4K 16:9 | Telas grandes e impressão |

Python:

```python
import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CENTOPEIA_API_KEY"],
    base_url="https://centopeia.io/openai/v1",
)

resposta = client.images.generate(
    model="gpt-image-2.5-sunburst",
    prompt=(
        "Suíte de luxo em um hotel 5 estrelas nos Alpes Suíços, "
        "janelas panorâmicas com vista para montanhas nevadas, "
        "lareira acesa, madeira nobre e pedra, luz quente ao entardecer, "
        "fotografia de arquitetura hiper-realista"
    ),
    size="1536x864",  # 16:9, largura e altura múltiplas de 16
    quality="high",   # low, medium, high, xhigh ou max
    n=1,
)

with open("suite_alpes.png", "wb") as arquivo:
    arquivo.write(base64.b64decode(resposta.data[0].b64_json))
print("Imagem salva em suite_alpes.png")
```

Node.js:

```javascript
import { writeFileSync } from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CENTOPEIA_API_KEY,
  baseURL: "https://centopeia.io/openai/v1",
});

const resposta = await client.images.generate({
  model: "gpt-image-2.5-sunburst",
  prompt:
    "Suíte de luxo em um hotel 5 estrelas nos Alpes Suíços, " +
    "janelas panorâmicas com vista para montanhas nevadas, " +
    "lareira acesa, madeira nobre e pedra, luz quente ao entardecer, " +
    "fotografia de arquitetura hiper-realista",
  size: "1536x864", // 16:9, largura e altura múltiplas de 16
  quality: "high",  // low, medium, high, xhigh ou max
  n: 1,
});

writeFileSync("suite_alpes.png", Buffer.from(resposta.data[0].b64_json, "base64"));
console.log("Imagem salva em suite_alpes.png");
```

cURL:

```bash
curl https://centopeia.io/openai/v1/images/generations \
  -H "Authorization: Bearer $CENTOPEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "Suíte de luxo em um hotel 5 estrelas nos Alpes Suíços, janelas panorâmicas com vista para montanhas nevadas, lareira acesa, madeira nobre e pedra, luz quente ao entardecer, fotografia de arquitetura hiper-realista",
    "size": "1536x864",
    "quality": "high",
    "n": 1
  }' | jq -r '.data[0].b64_json' | base64 --decode > suite_alpes.png
```

### Modelos disponíveis

Python:

```python
for modelo in client.models.list():
    print(modelo.id)
```

Node.js:

```javascript
for await (const modelo of client.models.list()) {
  console.log(modelo.id);
}
```

cURL:

```bash
curl https://centopeia.io/openai/v1/models \
  -H "Authorization: Bearer $CENTOPEIA_API_KEY"
```

## Claude (Anthropic)

### Streaming

Python:

```python
with client.messages.stream(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Conte uma história curta."}],
) as stream:
    for texto in stream.text_stream:
        print(texto, end="", flush=True)
```

Node.js:

```javascript
const stream = client.messages.stream({
  model: "claude-sonnet-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Conte uma história curta." }],
});
stream.on("text", (texto) => process.stdout.write(texto));
await stream.finalMessage();
```

cURL:

```bash
curl -N https://centopeia.io/anthropic/v1/messages \
  -H "x-api-key: $CENTOPEIA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "Conte uma história curta."}]
  }'
```

### Contagem de tokens

Python:

```python
contagem = client.messages.count_tokens(
    model="claude-sonnet-5-5",
    messages=[{"role": "user", "content": "Quantos tokens tem esta frase?"}],
)
print(contagem.input_tokens)
```

Node.js:

```javascript
const contagem = await client.messages.countTokens({
  model: "claude-sonnet-5-5",
  messages: [{ role: "user", content: "Quantos tokens tem esta frase?" }],
});
console.log(contagem.input_tokens);
```

cURL:

```bash
curl https://centopeia.io/anthropic/v1/messages/count_tokens \
  -H "x-api-key: $CENTOPEIA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "messages": [{"role": "user", "content": "Quantos tokens tem esta frase?"}]
  }'
```

## Modelos 3D a partir de imagens

Endereço base: https://centopeia.io/meshy/openapi/v1 (API compatível com a da Meshy). Crie a tarefa, guarde o `result` e consulte até o status ser `SUCCEEDED`; os arquivos ficam em `model_urls` (GLB, FBX, OBJ, USDZ) por 3 dias. Cobrança pelos créditos que a tarefa consome; tarefas com falha não são cobradas.

Python:

```python
import base64, os, sys, time
import requests

BASE = "https://centopeia.io/meshy/openapi/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['CENTOPEIA_API_KEY']}"}

# Foto do objeto (JPG, PNG ou WebP, até 20 MB). Também aceita uma URL pública HTTPS.
with open("foto.png", "rb") as arquivo:
    imagem = "data:image/png;base64," + base64.b64encode(arquivo.read()).decode()

r = requests.post(f"{BASE}/image-to-3d", headers=HEADERS, json={
    "image_url": imagem,
    "ai_model": "meshy-6-lite",   # rascunho rápido: 5 créditos
    "should_texture": False,      # True gera textura (mais créditos)
})
if not r.ok:
    sys.exit(f"Erro {r.status_code} ({r.json().get('code')}): {r.json().get('message')}")
tarefa = r.json()["result"]

while True:
    t = requests.get(f"{BASE}/image-to-3d/{tarefa}", headers=HEADERS).json()
    print(t.get("status"), t.get("progress"), "%")
    if t.get("status") in ("SUCCEEDED", "FAILED", "CANCELED"):
        break
    time.sleep(5)

if t["status"] == "SUCCEEDED":
    print("Modelo GLB:", t["model_urls"]["glb"])  # baixe em até 3 dias
else:
    print("A tarefa não foi concluída:", t.get("task_error", {}).get("message"))
```

Node.js:

```javascript
import { readFile } from "node:fs/promises";

const BASE = "https://centopeia.io/meshy/openapi/v1";
const headers = {
  Authorization: `Bearer ${process.env.CENTOPEIA_API_KEY}`,
  "Content-Type": "application/json",
};

// Foto do objeto (JPG, PNG ou WebP, até 20 MB). Também aceita uma URL pública HTTPS.
const imagem = "data:image/png;base64," + (await readFile("foto.png")).toString("base64");

const r = await fetch(`${BASE}/image-to-3d`, {
  method: "POST",
  headers,
  body: JSON.stringify({ image_url: imagem, ai_model: "meshy-6-lite", should_texture: false }),
});
const criada = await r.json();
if (!r.ok) throw new Error(`Erro ${r.status} (${criada.code}): ${criada.message}`);

let t;
do {
  await new Promise((ok) => setTimeout(ok, 5000));
  t = await fetch(`${BASE}/image-to-3d/${criada.result}`, { headers }).then((x) => x.json());
  console.log(t.status, t.progress, "%");
} while (!["SUCCEEDED", "FAILED", "CANCELED"].includes(t.status));

console.log(t.status === "SUCCEEDED" ? t.model_urls.glb : t.task_error?.message);
```

cURL:

```bash
# 1. Crie a tarefa (foto local enviada como data URI)
IMAGEM="data:image/png;base64,$(base64 -w0 foto.png)"
curl https://centopeia.io/meshy/openapi/v1/image-to-3d \
  -H "Authorization: Bearer $CENTOPEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"image_url\": \"$IMAGEM\", \"ai_model\": \"meshy-6-lite\", \"should_texture\": false}"

# 2. Consulte com o "result" retornado até "status" ser SUCCEEDED
curl https://centopeia.io/meshy/openapi/v1/image-to-3d/ID_DA_TAREFA \
  -H "Authorization: Bearer $CENTOPEIA_API_KEY"
```

## Imagem, vídeo, áudio e modelos abertos

Use o SDK oficial do Replicate apontando para https://centopeia.io/replicate/v1. Disponíveis os modelos listados no seu painel (aba Modelos). Cobrança pelo que a tarefa produz (imagens, segundos de vídeo, tokens ou tempo de processamento). Webhooks e arquivos enviados não são aceitos: envie as entradas como URL ou data URI e consulte a predição.

Python:

```python
import os
import urllib.request
import replicate

client = replicate.Client(
    api_token=os.environ["CENTOPEIA_API_KEY"],
    base_url="https://centopeia.io/replicate",
)

links = client.run(
    "black-forest-labs/flux-schnell",
    input={"prompt": "Uma centopeia verde lendo um livro, ilustração"},
    use_file_output=False,  # devolve os links dos arquivos gerados
)
urllib.request.urlretrieve(links[0], "imagem.webp")  # o link expira: guarde o arquivo
print("Imagem salva em imagem.webp")
```

Node.js:

```javascript
import { writeFile } from "node:fs/promises";
import Replicate from "replicate";

const replicate = new Replicate({
  auth: process.env.CENTOPEIA_API_KEY,
  baseUrl: "https://centopeia.io/replicate/v1",
  useFileOutput: false, // devolve os links dos arquivos gerados
});

const links = await replicate.run("black-forest-labs/flux-schnell", {
  input: { prompt: "Uma centopeia verde lendo um livro, ilustração" },
});
const arquivo = await fetch(links[0]); // o link expira: guarde o arquivo
await writeFile("imagem.webp", Buffer.from(await arquivo.arrayBuffer()));
console.log("Imagem salva em imagem.webp");
```

cURL:

```bash
curl https://centopeia.io/replicate/v1/models/black-forest-labs/flux-schnell/predictions \
  -H "Authorization: Bearer $CENTOPEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait" \
  -d '{"input": {"prompt": "Uma centopeia verde lendo um livro, ilustração"}}'
```

### Tarefas longas (vídeo, transcrição)

Python:

```python
import os
import replicate

client = replicate.Client(
    api_token=os.environ["CENTOPEIA_API_KEY"],
    base_url="https://centopeia.io/replicate",
)

# Tarefas longas (vídeo, transcrição): crie, guarde o id e espere o resultado.
predicao = client.models.predictions.create(
    model="bytedance/seedance-1-lite",
    input={"prompt": "Drone sobrevoando uma floresta ao amanhecer", "duration": 5},
)
predicao.wait()
print(predicao.status, predicao.output)  # links dos arquivos: baixe em até 1 hora
```

Node.js:

```javascript
import Replicate from "replicate";

const replicate = new Replicate({
  auth: process.env.CENTOPEIA_API_KEY,
  baseUrl: "https://centopeia.io/replicate/v1",
});

// Tarefas longas (vídeo, transcrição): crie, guarde o id e espere o resultado.
let predicao = await replicate.predictions.create({
  model: "bytedance/seedance-1-lite",
  input: { prompt: "Drone sobrevoando uma floresta ao amanhecer", duration: 5 },
});
predicao = await replicate.wait(predicao);
console.log(predicao.status, predicao.output); // baixe o arquivo em até 1 hora
```

cURL:

```bash
# 1. Crie a predição e guarde o "id"
curl https://centopeia.io/replicate/v1/models/bytedance/seedance-1-lite/predictions \
  -H "Authorization: Bearer $CENTOPEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"prompt": "Drone sobrevoando uma floresta ao amanhecer", "duration": 5}}'

# 2. Consulte até "status" ser "succeeded"
curl https://centopeia.io/replicate/v1/predictions/ID_DA_PREDICAO \
  -H "Authorization: Bearer $CENTOPEIA_API_KEY"
```

### Modelos disponíveis em mídia e 3D

O catálogo abaixo é o padrão; os modelos liberados para a sua empresa, com preços em reais, ficam na aba Modelos do painel. Os parâmetros de `input` de cada modelo são os mesmos da página dele no Replicate.

| Categoria | Para que serve | Modelos (id) |
| --- | --- | --- |
| Modelos 3D | Modelo 3D (GLB, FBX, OBJ, USDZ) a partir de uma ou várias fotos | `image-to-3d`, `multi-image-to-3d` |
| Imagens | Gerar e editar imagens a partir de texto | `black-forest-labs/flux-schnell`, `google/nano-banana`, `bytedance/sdxl-lightning-4step` |
| Vídeos | Vídeos curtos a partir de texto ou imagem | `wan-video/wan-2.2-i2v-fast`, `prunaai/p-video`, `bytedance/seedance-1-lite` |
| Texto (modelos abertos) | Conversa e geração de texto com Llama 3 | `meta/meta-llama-3-8b-instruct`, `meta/meta-llama-3-70b-instruct`, `meta/meta-llama-3-8b` |
| Ampliar e restaurar imagens | Aumentar a resolução e recuperar rostos | `nightmareai/real-esrgan`, `tencentarc/gfpgan`, `sczhou/codeformer` |
| Remover fundo | Recortar o objeto principal de uma imagem | `851-labs/background-remover`, `lucataco/remove-bg`, `cjwbw/rembg` |
| Transcrever áudio | Fala para texto, com marcação de tempo e falantes | `openai/whisper`, `vaibhavs10/incredibly-fast-whisper`, `victor-upmeet/whisperx` |
| Gerar fala | Texto para áudio com vozes naturais | `minimax/speech-02-turbo`, `jaaari/kokoro-82m`, `lucataco/xtts-v2` |

## Frameworks

LangChain (Python):

```python
from langchain_openai import ChatOpenAI
from langchain_anthropic import ChatAnthropic

gpt = ChatOpenAI(
    model="gpt-5.5",
    api_key=CHAVE_CENTOPEIA,
    base_url="https://centopeia.io/openai/v1",
    max_tokens=500,
)
claude = ChatAnthropic(
    model="claude-sonnet-5-5",
    api_key=CHAVE_CENTOPEIA,
    base_url="https://centopeia.io/anthropic",
    max_tokens=1024,
)
print(claude.invoke("Olá!").content)
```

Vercel AI SDK (Node.js). Atenção: no AI SDK o endereço da Anthropic inclui `/v1`.

```javascript
import { createOpenAI } from "@ai-sdk/openai";
import { createAnthropic } from "@ai-sdk/anthropic";
import { generateText } from "ai";

const openai = createOpenAI({
  apiKey: process.env.CENTOPEIA_API_KEY,
  baseURL: "https://centopeia.io/openai/v1",
});
const anthropic = createAnthropic({
  apiKey: process.env.CENTOPEIA_API_KEY,
  baseURL: "https://centopeia.io/anthropic/v1",
});

const { text } = await generateText({
  model: anthropic("claude-sonnet-5-5"),
  maxOutputTokens: 500,
  prompt: "Olá!",
});
```

## Endpoints disponíveis

| Modelo | Método | Endpoint | Para que serve |
| --- | --- | --- | --- |
| GPT | POST | `https://centopeia.io/openai/v1/chat/completions` | Conversas e completions |
| GPT | POST | `https://centopeia.io/openai/v1/responses` | Responses API |
| GPT | POST | `https://centopeia.io/openai/v1/embeddings` | Vetores para busca e RAG |
| GPT | POST | `https://centopeia.io/openai/v1/images/generations` | Geração de imagens por texto |
| GPT | GET | `https://centopeia.io/openai/v1/models` | Modelos disponíveis |
| Claude | POST | `https://centopeia.io/anthropic/v1/messages` | Mensagens com o Claude |
| Claude | POST | `https://centopeia.io/anthropic/v1/messages/count_tokens` | Contagem de tokens |
| Claude | GET | `https://centopeia.io/anthropic/v1/models` | Modelos disponíveis |
| 3D | POST | `https://centopeia.io/meshy/openapi/v1/image-to-3d` | Modelo 3D a partir de uma imagem |
| 3D | POST | `https://centopeia.io/meshy/openapi/v1/multi-image-to-3d` | Modelo 3D a partir de 1 a 4 fotos |
| 3D | GET | `https://centopeia.io/meshy/openapi/v1/image-to-3d/{id}` | Situação e arquivos da tarefa |
| Mídia | POST | `https://centopeia.io/replicate/v1/models/{dono}/{nome}/predictions` | Imagem, vídeo, áudio e modelos abertos |
| Mídia | GET | `https://centopeia.io/replicate/v1/predictions/{id}` | Situação e resultado |
| Mídia | POST | `https://centopeia.io/replicate/v1/predictions/{id}/cancel` | Cancelar |
| MCP | POST | `https://centopeia.io/mcp` | Servidor Model Context Protocol (OAuth 2.1 e token pessoal) |

Não disponíveis: arquivos, batches, assistants, áudio da OpenAI, edição de imagens da OpenAI, respostas salvas (`responses/{id}`), listagens de tarefas de mídia, envio de arquivos e webhooks. Tamanho máximo por requisição: 32 MB.

## Chaves com limite de gasto

- Informe sempre o limite de saída (veja "Essencial").
- Ferramentas: apenas function calling; ferramentas hospedadas pelo provedor não são aceitas.
- Envie o histórico da conversa a cada chamada (`messages` ou `input`); `previous_response_id`, `conversation` e `background` não são aceitos.
- Imagens: `size` e `quality` explícitos, e até uma imagem por chamada em streaming.
- O valor máximo da chamada é reservado no início e ajustado ao consumo real no fim.
- Mídia e 3D: o custo máximo estimado da tarefa é reservado ao criá-la; quando ela termina, você paga só o que foi produzido. Tarefas que falham ou são canceladas antes de começar não são cobradas. Sem saldo para a reserva, a criação retorna 402.

## Assistentes de IA (MCP)

Conecte Claude, ChatGPT, Cursor, VS Code ou Claude Code à sua conta. O assistente usa os modelos da CentopeIA (texto, imagem, embeddings, vídeo, áudio e 3D, inclusive com o mesmo corpo da API oficial), consulta modelos e preços, escreve a integração com o código certo, cria e ajusta chaves, acompanha saldo e consumo, gera recargas Pix e gerencia a equipe, sempre com as permissões do seu papel (Owner, Admin ou Developer).

Endereço do servidor: `https://centopeia.io/mcp`

O login é feito pelo navegador (OAuth): o assistente abre a página de autorização, você entra com a sua conta, escolhe a chave que paga os modelos usados pelo assistente (uma chave existente da empresa ou uma dedicada) e aprova. Valem as regras da chave escolhida, como numa chamada pela API; o segredo da chave nunca passa pelo assistente. Para trocar a chave ou desconectar, use o painel, aba Assistentes de IA.

- Claude: Configurações, Conectores, Adicionar conector personalizado, cole o endereço.
- ChatGPT: Configurações, Aplicativos e conectores, modo desenvolvedor, crie um conector com o endereço e autenticação OAuth.
- Claude Code: `claude mcp add --transport http centopeia https://centopeia.io/mcp`
- Cursor (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "centopeia": {
      "url": "https://centopeia.io/mcp"
    }
  }
}
```

- VS Code (`.vscode/mcp.json`):

```json
{
  "servers": {
    "centopeia": {
      "type": "http",
      "url": "https://centopeia.io/mcp"
    }
  }
}
```

- Ferramentas sem login pelo navegador: gere um token pessoal (`sk-ctp-mcp-...`) no painel e envie no cabeçalho `Authorization`:

```json
{
  "mcpServers": {
    "centopeia": {
      "url": "https://centopeia.io/mcp",
      "headers": {
        "Authorization": "Bearer ${CENTOPEIA_MCP_TOKEN}"
      }
    }
  }
}
```

Segurança:

- Ações que não têm volta (revogar chave, remover pessoa), recargas Pix e chamadas a modelos com custo máximo acima de R$ 1,00 pedem confirmação em duas etapas: o assistente mostra um resumo e só executa depois que você concordar.
- Chaves novas e senhas provisórias nunca aparecem no chat: chegam por um link seguro de uso único, válido por 10 minutos, que só abre com a sua conta.
- O uso de modelos pelos assistentes respeita um teto diário por pessoa (padrão R$ 5,00), ajustável por Owner e Admin, além dos limites da chave escolhida. Desconectar só revoga a chave se ela for dedicada.
- Tudo o que cada assistente faz fica registrado na aba Assistentes de IA.

| Grupo | Ferramentas |
| --- | --- |
| Usar modelos | gerar_texto, gerar_imagem, gerar_embeddings, chamar_api, criar_tarefa_midia, consultar_tarefa_midia, cancelar_tarefa_midia |
| Integração | listar_modelos, detalhes_do_modelo, exemplo_de_codigo, documentacao, diagnosticar_erro, verificar_configuracao |
| Chaves | listar_chaves, criar_chave, ajustar_chave, revogar_chave |
| Saldo | ver_saldo, ver_extrato, ver_consumo, recarregar_pix, pix_fixo, ajustar_teto_diario |
| Equipe | listar_equipe, convidar_membro, alterar_membro, remover_membro |

## Erros

Os erros seguem o formato de cada provedor, então os SDKs lançam as exceções habituais (`AuthenticationError`, `PermissionDeniedError`, `RateLimitError`).

| Status | Significado | O que fazer |
| --- | --- | --- |
| 400 | Faltou o limite de saída ou uma opção não é aceita. | Inclua max_tokens (ou equivalente) e revise os parâmetros. |
| 401 | Chave inválida ou revogada. | Confira a variável de ambiente ou peça uma nova chave. |
| 402 | Saldo insuficiente para iniciar uma tarefa de mídia ou 3D. | Recarregue os créditos da empresa ou ajuste o limite da chave. |
| 403 | Provedor ou serviço não habilitado, ou saldo de créditos / limite da chave atingido. | Fale com o nosso time para recarregar os créditos, ajustar o limite da chave ou liberar o serviço. |
| 404 | Endpoint, modelo ou tarefa não disponível. | Use um dos endpoints e modelos listados. Tarefas só podem ser consultadas pela empresa que as criou. |
| 409 | Modelo ainda não liberado para chaves com limite. | Escolha outro modelo ou fale com o nosso time. |
| 413 | Requisição acima de 32 MB. | Reduza o conteúdo enviado. |
| 429 | Muitas chamadas simultâneas. | Os SDKs tentam de novo sozinhos. Aguarde alguns segundos. |
| 503 | Indisponibilidade temporária. | Tente novamente. O cabeçalho Retry-After indica quando. |

Python:

```python
import openai

try:
    resposta = client.chat.completions.create(...)
except openai.AuthenticationError:
    print("Confira a chave CentopeIA configurada.")
except openai.PermissionDeniedError as erro:
    print(erro.message)  # ex.: saldo de créditos ou limite da chave atingido
except openai.RateLimitError:
    print("Muitas chamadas ao mesmo tempo. Tente de novo em instantes.")
```

Node.js:

```javascript
import OpenAI from "openai";

try {
  const resposta = await client.chat.completions.create({ /* ... */ });
} catch (erro) {
  if (erro instanceof OpenAI.AuthenticationError) {
    console.error("Confira a chave CentopeIA configurada.");
  } else if (erro instanceof OpenAI.PermissionDeniedError) {
    console.error(erro.message); // ex.: saldo de créditos ou limite da chave atingido
  } else {
    throw erro;
  }
}
```