OpenAPI 3.1

Referência da API de cliente

Esta página descreve o pedido e a resposta de inferência de cliente suportados. Descarregue o documento OpenAPI legível por máquina para utilizar com ferramentas.

Descarregar JSON OpenAPI

Exemplos de API para modelos

Escolha um identificador de modelo publicado, protocolo de API e idioma para ver um exemplo de pedido. Mantenha as chaves de API dos clientes num servidor de confiança.

Modelo

Idioma

Requisitos do protocolo

Os pedidos compatíveis com OpenAI usam POST /chat/completions no URL base de API do cliente configurado (por predefinição https://fusionpointai.com/api/v1). Autentique com Authorization: Bearer e uma chave de cliente com acesso à inferência. O URL completo predefinido é https://fusionpointai.com/api/v1/chat/completions.

Capacidades suportadas

O endpoint atual de chat compatível com OpenAI processa mensagens de texto síncronas. Este endpoint não suporta streaming nem chamadas a ferramentas.

Instalar um cliente

Instale os clientes de Python e Node.js como pacotes separados:

Python: pip install openai anthropic

Node.js: npm install openai @anthropic-ai/sdk

curl 'https://fusionpointai.com/api/v1/chat/completions' \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "Astra 6",
    "messages": [
        {
            "role": "user",
            "content": "Summarize this in one sentence."
        }
    ],
    "temperature": 0.7,
    "max_tokens": 300
}'

Padrões de pedido

Configurar chaves de API em segurança

Crie uma chave de API de cliente com acesso à inferência e disponibilize-a a um processo no servidor através do gestor de segredos ou do ambiente.

Defina FUSIONPOINTAI_API_KEY no ambiente do servidor; não inclua a chave no código do browser nem a submeta no controlo de versões.
Use HTTPS e limite a chave à conta e às permissões de inferência necessárias à aplicação.
Oculte os cabeçalhos authorization e x-api-key em registos, rastos e pedidos de suporte; revogue uma chave se puder ter sido exposta.

export FUSIONPOINTAI_API_KEY="YOUR_CUSTOMER_API_KEY"

Selecionar um identificador exato de modelo

O campo model é um valor de encaminhamento, não um rótulo de apresentação. Escolha um identificador publicado no catálogo atual de modelos.

Selecione um modelo ativo ou legado marcado como disponível para inferência.
Copie o identificador exatamente, incluindo pontuação e sufixos de versão; nunca o deduza do nome do modelo.
Se não houver identificador publicado, aguarde que o catálogo o forneça em vez de adivinhar um valor.

model_id = "Astra 6"
# Use this exact identifier with either protocol.

Enviar mensagens de sistema e de várias interações

Mantenha as mensagens da conversa pela ordem original e use apenas as funções e estruturas de conteúdo suportadas pelo protocolo e modelo selecionados.

Nos pedidos compatíveis com OpenAI, envie mensagens system, user e assistant ordenadas, com conteúdo em texto.
Em Claude Messages, envie a instrução de sistema suportada e os turnos user/assistant ordenados nos campos nativos do protocolo.
Conserve apenas o contexto de conversa necessário à aplicação e respeite os limites de contexto do modelo.

response = client.messages.create(
    model="Astra 6",
    max_tokens=512,
    system="Answer in clear, concise German.",
    messages=[
        {"role": "user", "content": "What is an API?"},
        {"role": "assistant", "content": "An API lets software exchange requests and responses."},
        {"role": "user", "content": "Give a practical example."},
    ],
)
for block in response.content:
    if block.type == "text":
        print(block.text)

Pedir respostas JSON

Quando a aplicação precisar de saída estruturada, valide a resposta face ao seu próprio esquema antes de a utilizar.

Use os controlos de saída estruturada suportados pelo protocolo escolhido e pelo modelo upstream selecionado.
Trate o JSON gerado como entrada não fiável: analise-o, valide campos e tipos obrigatórios e trate saídas inválidas.
Não presuma que uma combinação de modelo e protocolo suporta modo JSON sem confirmação na documentação do modelo.

import json

# JSON is generated content, not trusted application input.
response = client.messages.create(
    model="Astra 6", max_tokens=256,
    messages=[{"role": "user", "content": 'Return only JSON with a string field named "summary". Explain an API in one sentence.'}],
)
text = "".join(block.text for block in response.content if block.type == "text")
try:
    result = json.loads(text)
    if not isinstance(result, dict) or not isinstance(result.get("summary"), str):
        raise ValueError("Unexpected response schema")
    print(result["summary"])
except (json.JSONDecodeError, ValueError) as error:
    print("Handle invalid model output:", error)

Receber saída SSE em tempo real

O streaming depende do protocolo e do modelo upstream selecionados; uma resposta JSON normal não é um fluxo.

O chat compatível com OpenAI devolve atualmente texto síncrono e não fornece streaming.
Em Claude Messages, use o modo stream quando o modelo upstream o suportar; o proxy encaminha eventos nativos enviados pelo servidor.
Consuma eventos à medida que chegam, termine corretamente ao concluir ou ocorrer um erro e não trate saída parcial como resposta completa.

# client is the Anthropic client configured above.
with client.messages.stream(
    model="Astra 6", max_tokens=512,
    messages=[{"role": "user", "content": "Explain API authentication."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final_message = stream.get_final_message()
print("\nStop reason:", final_message.stop_reason)

Tratar ferramentas, blocos de conteúdo e erros

Mantenha intactas as estruturas nativas do protocolo e defina explicitamente o comportamento da aplicação para chamadas a ferramentas, conteúdo multimodal e falhas.

O chat compatível com OpenAI não suporta atualmente chamadas a ferramentas nem blocos de conteúdo não textual.
Claude preserva blocos nativos e dados de utilização/resultados de ferramentas quando o modelo upstream os suporta; valide nomes e argumentos antes de executar ferramentas.
Verifique o estado HTTP e o corpo da resposta, distinga falhas de autenticação, permissão, validação e limite e repita erros transitórios com espera crescente.

import json
from datetime import datetime, timezone
from anthropic import APIError

messages = [{"role": "user", "content": "What time is it in UTC?"}]
tools = [{
    "name": "current_utc_time", "description": "Read the current UTC time.",
    "input_schema": {"type": "object", "properties": {}, "additionalProperties": False},
}]
try:
    reply = client.messages.create(model="Astra 6", max_tokens=256, messages=messages, tools=tools)
    results = []
    for block in reply.content:
        if block.type == "tool_use":
            if block.name != "current_utc_time" or block.input != {}:
                raise ValueError("Unapproved tool request")
            results.append({"type": "tool_result", "tool_use_id": block.id,
                            "content": json.dumps({"utc": datetime.now(timezone.utc).isoformat()})})
    if results:
        messages.append({"role": "assistant", "content": reply.content})
        messages.append({"role": "user", "content": results})
        reply = client.messages.create(model="Astra 6", max_tokens=256, messages=messages, tools=tools)
    print("".join(block.text for block in reply.content if block.type == "text"))
except APIError as error:
    # Log status only; never log keys or private prompts.
    print("API request failed:", getattr(error, "status_code", None))

Perguntas frequentes

Posso usar o nome apresentado do modelo num pedido?

Use apenas o identificador exato publicado para inferência. O nome apresentado não é um valor de encaminhamento e nunca deve adivinhar um identificador não publicado.

Que variável de ambiente contém a chave do cliente?

Use FUSIONPOINTAI_API_KEY nos dois protocolos. Mantenha o valor num ambiente de servidor de confiança, fora do código cliente e dos registos.

Que URL deve usar o cliente OpenAI?

Use o URL base configurado para a API do cliente, cujo valor predefinido é https://fusionpointai.com/api/v1. O endpoint de chat acrescenta /chat/completions.

Porque difere o URL base do Claude SDK do usado em cURL?

O Anthropic SDK acrescenta /v1/messages; defina o URL base como https://fusionpointai.com/api. Um pedido HTTP direto usa o URL completo /api/v1/messages.

O chat compatível com OpenAI suporta streaming ou ferramentas?

Não. O endpoint atual suporta apenas mensagens de texto síncronas; streaming e chamadas a ferramentas não estão disponíveis.

Todos os modelos Claude suportam blocos, ferramentas ou streaming?

Não. Estas funcionalidades nativas são preservadas quando o modelo upstream selecionado as suporta. Consulte as capacidades do modelo e trate pedidos não suportados.

Claude Messages · `POST /messages`

Os pedidos Claude Messages usam POST /api/v1/messages. Envie a chave do cliente em x-api-key e defina anthropic-version como 2023-06-01. O URL base do Anthropic SDK é https://fusionpointai.com/api, porque o SDK acrescenta /v1/messages; também é suportada autenticação bearer.

O proxy Claude Messages preserva blocos de conteúdo nativos, dados de ferramentas e streaming real de eventos enviados pelo servidor quando o modelo upstream selecionado os suporta.

Campo	Tipo	Obrigatório	Restrições
`model`	`string`	Sim	`{"minLength":1,"maxLength":160}`
`max_tokens`	`integer`	Sim	`{"minimum":1,"maximum":100000}`
`messages`	`array`	Sim	`{"minItems":1,"maxItems":100,"items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","maxLength":80}},"additionalProperties":true}}]}}}}`
`system`	`string \| array`	Não	`{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","required":["type","text"],"properties":{"type":{"const":"text"},"text":{"type":"string"}},"additionalProperties":true}}]}`
`stream`	`boolean`	Não	`{"default":false}`
`temperature`	`number`	Não	`{"minimum":0,"maximum":1}`
`top_p`	`number`	Não	`{"minimum":0,"maximum":1}`
`top_k`	`integer`	Não	`{"minimum":0,"maximum":100000}`
`stop_sequences`	`array`	Não	`{"items":{"type":"string"}}`
`tools`	`array`	Não	`{"items":{"type":"object","additionalProperties":true}}`
`tool_choice`	`object`	Não	`{"additionalProperties":true}`
`thinking`	`object`	Não	`{"additionalProperties":true}`
`metadata`	`object`	Não	`{"additionalProperties":true}`
`output_config`	`object`	Não	`{"additionalProperties":true}`
`service_tier`	`string`	Não	`[]`

{
    "id": "msg_example",
    "type": "message",
    "role": "assistant",
    "model": "Astra 6",
    "content": [
        {
            "type": "text",
            "text": "A concise answer to the supplied question."
        }
    ],
    "stop_reason": "end_turn",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 12,
        "output_tokens": 10
    }
}

{"type":"error","error":{"type":"authentication_error","message":"Invalid or missing API key."}}

Início rápido com SDK

Utilize o URL base de produção com um cliente Python ou Node.js compatível, ou envie o mesmo pedido JSON com cURL.

URL base da API: https://fusionpointai.com/api/v1

Envie a chave de API de cliente no cabeçalho Authorization: Bearer. A chave tem de ter o âmbito ai:inference e acesso da conta ao serviço. Guarde-a num servidor de confiança.

# Install the client for your application language.
# Python:
python -m pip install openai
# Node.js:
npm install openai

# Bash: enter the key without storing it in shell history.
read -rs -p 'FusionPointAI API key: ' FUSIONPOINTAI_API_KEY
export FUSIONPOINTAI_API_KEY
printf '\n'
# After finishing:
# unset FUSIONPOINTAI_API_KEY

curl 'https://fusionpointai.com/api/v1/chat/completions' \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "Jurassic-2",
    "messages": [
        {
            "role": "user",
            "content": "Summarize this in one sentence."
        }
    ],
    "temperature": 0.7,
    "max_tokens": 300
}'

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="Jurassic-2",
    messages=[{"role": "user", "content": "Summarize this in one sentence."}],
    temperature=0.7,
    max_tokens=300,
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FUSIONPOINTAI_API_KEY,
  baseURL: "https://fusionpointai.com/api/v1",
});

const response = await client.chat.completions.create({
  model: "Jurassic-2",
  messages: [{ role: "user", content: "Summarize this in one sentence." }],
  temperature: 0.7,
  max_tokens: 300,
});
console.log(response.choices[0].message.content);

OpenAI · Campos do pedido

Os valores de modelo são os identificadores exatos registados e atualmente publicados para inferência. Se não houver nenhum publicado, consulte o catálogo de fornecedores antes de enviar um pedido.

Campo	Tipo	Obrigatório	Restrições
`model`	`string`	Sim	No máximo, 160 caracteres; utilize um identificador exato publicado.
`messages`	`array`	Sim	1 a 100 mensagens, enviadas pela ordem indicada.
`messages[].role`	`string`	Sim	system, user ou assistant.
`messages[].content`	`string`	Sim	No máximo, 100 000 caracteres por mensagem.
`temperature`	`number`	Não	Entre 0 e 2.
`max_tokens`	`integer`	Não	Entre 1 e 100 000; o modelo pode impor um limite inferior.

Resposta bem-sucedida

Uma resposta JSON bem-sucedida contém id, object (chat.completion), created, model e choices. Uma opção inclui index, uma mensagem assistant e finish_reason. Também podem ser devolvidos dados de utilização de tokens.

{
    "id": "chatcmpl_example",
    "object": "chat.completion",
    "created": 1700000000,
    "model": "Jurassic-2",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "A concise summary of the supplied text."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 12,
        "completion_tokens": 10,
        "total_tokens": 22
    }
}

Campo	Tipo	Significado
`id`	`string`	Identificador único da conclusão.
`object`	`string`	Tipo de resposta: chat.completion.
`created`	`integer`	Hora de criação em formato de carimbo de data/hora Unix.
`model`	`string`	Identificador do modelo utilizado para a conclusão.
`choices`	`array`	Alternativas de conclusão com uma mensagem assistant e um motivo de conclusão.
`usage`	`object`	Contagens de tokens, quando devolvidas.

Limites de pedidos e erros

As subscrições de clientes em produção não contabilizam pedidos nem tokens face a uma quota; as chaves sandbox usam a franquia mensal publicada. Continuam a aplicar-se janelas de contexto, limites de saída e controlos temporários de tráfego. Chat Completions é texto síncrono; Claude Messages preserva blocos de conteúdo nativos, ferramentas e SSE suportados. Consulte os esquemas de cada operação antes de enviar pedidos.

A operação de conversação devolve as falhas de validação e do fornecedor num objeto de erro. O middleware de autenticação e de âmbito pode, em alternativa, devolver um campo message no nível superior; o estado e o formato da resposta dependem da camada que rejeitou o pedido.

Estado HTTP	Significado
`200`	Conclusão criada com êxito.
`400`	Corpo do pedido ou parâmetro inválido.
`401`	Chave de API bearer em falta ou inválida.
`403`	Falta o âmbito obrigatório da chave ou o acesso à conta.
`429`	Foi aplicado um limite da aplicação ou um controlo temporário de tráfego a montante; volte a tentar com intervalos crescentes.
`500`	O serviço não conseguiu devolver uma conclusão utilizável.