Referência da API tAI

O endpoint

Tudo nesta API passa por um único URL:

# URL base
https://api.artfical.com/v1

Existe um único endpoint de conclusão, POST /v1/chat/completions, e um único endpoint de listagem apenas de leitura, GET /v1/models. Essa é toda a superfície da API. Não há um endpoint separado por modelo, não há um endpoint separado para streaming versus não-streaming (o mesmo URL trata ambos, alternado por um campo no corpo do pedido), e não há um endpoint separado para turnos com chamadas de ferramentas. Se já desenvolveu algo sobre a API Chat Completions da OpenAI, os endpoints de inferência do GitHub, ou qualquer um dos muitos fornecedores que oferecem um formato compatível com a OpenAI, isto já lhe será familiar. Essa semelhança é deliberada: apontar um cliente já compatível com a OpenAI (o pacote oficial openai para Python ou Node, o LangChain, o LlamaIndex, um agente de programação como o OpenCode, ou o seu próprio wrapper) para https://api.artfical.com/v1 com uma chave de API da tAI deve funcionar com pouca ou nenhuma alteração de código.

O caminho mais rápido até ao primeiro pedido

São necessárias três coisas: um workspace em console.artfical.com, uma chave de API criada a partir da página de chaves de API nesse workspace, e qualquer cliente HTTP. Eis a versão mais curta, usando curl:

# Substitua tai-sk-... pela sua própria chave
curl https://api.artfical.com/v1/chat/completions \
  -H "Authorization: Bearer tai-sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tai-4.1",
    "messages": [{"role": "user", "content": "Merhaba, kendini tanıt."}]
  }'

Esse único pedido já é uma integração completa e funcional. Tudo o resto nesta secção, streaming, chamada de ferramentas, entrada de imagens, controlos de amostragem, é uma camada opcional sobre este mesmo formato, não uma API diferente para aprender. A página Conclusões de chat percorre o pedido e a resposta completos em detalhe; a página Autenticação aborda como a própria chave é emitida, delimitada em âmbito e rodada.

Como esta secção está organizada

As páginas aqui são agrupadas para corresponder à ordem em que a maioria das pessoas realmente precisa delas, não à ordem em que a implementação subjacente por acaso está organizada. O primeiro grupo, introdução, é a parte de que todos precisam, independentemente do que estejam a construir: como autenticar, o formato de um pedido e de uma resposta, em que é que o streaming difere de uma única resposta bloqueante, e como descobrir que modelos existem e o que cada um custa e suporta. O segundo grupo, opções do pedido, cobre tudo o que é opcional sobre um pedido básico: os controlos de amostragem que moldam a forma como uma resposta é gerada, como dar ao modelo ferramentas que ele pode pedir para chamar, e como enviar uma imagem junto com texto. O terceiro grupo, referência, destina-se a ser consultado em vez de lido do início ao fim: o formato exato de uma resposta de erro e o que cada tipo significa, como funciona a limitação de taxa e que cabeçalhos a refletem, a tabela de preços por modelo, e uma página especificamente para quem está a migrar uma integração existente com o SDK da OpenAI, cobrindo o que é suportado tal como está e o que não é.

Para quem é esta secção

Esta secção é escrita para alguém que está a programar diretamente contra a API, seja um serviço de backend, um script, ou uma framework de agentes como o OpenCode que trata a tAI como um de vários fornecedores compatíveis com a OpenAI intermutáveis. Pressupõe familiaridade com pedidos HTTP e leitura de JSON, mas nenhum conhecimento prévio da tAI especificamente. Se, em vez disso, procura como usar a tAI através do próprio produto de chat, isso é coberto pela documentação principal da tAI, não por esta secção. Se procura como a tAI é avaliada quanto à segurança e com que salvaguardas o produto é construído, essa é a secção Segurança. Esta secção está delimitada especificamente à API HTTP voltada para o programador: o que envia, o que recebe de volta, e o que significa cada campo e cabeçalho.

Uma nota sobre estabilidade

Os formatos de pedido e resposta documentados nesta secção são os que pretendemos manter estáveis. A adição de um campo é algo que deve esperar ao longo do tempo, à medida que a API cresce; um campo documentado mudar de significado ou desaparecer sem substituição não é algo que façamos de ânimo leve. Onde algo é genuinamente provisório ou tem probabilidade de mudar, a página relevante diz isso explicitamente, em vez de o deixar descobrir da pior forma. Se um campo ou comportamento não é mencionado em nenhum ponto desta secção, trate-o como não fazendo parte do contrato suportado, mesmo que o observe numa resposta, uma vez que pode mudar ou desaparecer sem aviso.