Claude API em Go

Pense em uma entrega registrada na portaria. O pacote tem destino, etiquetas obrigatórias, conteúdo e um comprovante de resposta. Uma chamada à Claude API segue a mesma disciplina: endpoint e método dão o destino; headers autenticam e versionam; JSON leva a mensagem; status e JSON de resposta confirmam o resultado. Se uma dessas partes some, o problema não é “a IA”; é um envelope incompleto que você consegue inspecionar.

Nesta aula, o foco é a api por dentro: http e json. O risco concreto é aceitar texto plausível sem verificar o protocolo que o produziu. Isso gera falhas difíceis de reproduzir, cobra chamadas durante testes e deixa credenciais próximas demais da lógica de negócio. A saída é dividir transporte, parsing e decisão em funções pequenas.

A Anthropic Messages API recebe POST /v1/messages. Uma chamada real inclui x-api-key, anthropic-version, content-type: application/json e, quando parte diretamente do navegador, anthropic-dangerous-direct-browser-access: true. Esse último header autoriza explicitamente o cenário CORS; ele não substitui autenticação nem torna aceitável enviar a chave ao backend da plataforma.

O modelo BYO deste curso é literal: você fornece a própria chave no editor. Ela é guardada no localStorage do seu navegador e NUNCA chega aos nossos servidores. O navegador envia a requisição direto para api.anthropic.com. Remover os dados do site apaga a chave local. Não cole uma chave em código, fixture, screenshot, commit ou mensagem de erro.

Cada exercício usa uma resposta gravada em testdata/recorded-response.json. O harness não abre socket e não consulta ambiente. Assim, a mesma entrada produz o mesmo resultado sem chave, cobrança ou instabilidade. A execução livre pode usar a API quando encontra uma chave; sem ela, volta para fixture e explica esse modo em vez de bloquear você.

O carrossel acompanha quatro estados: bytes de entrada, parsing, decisão e saída. A fronteira visual ajuda a localizar defeitos. Se o JSON não decodifica, não culpe a regra. Se os dados decodificam mas falham na validação, não repita a requisição. Essa separação reduz custo e tempo de diagnóstico.

Este programa monta uma requisição real sem enviá-la. Assim você inspeciona método, headers e JSON como dados antes de envolver rede.

{/* <!-- chunk:1 --> */}

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

O tipo descreve o corpo mínimo de Messages. Messages continua uma lista porque a mesma forma sustenta o chat da próxima aula.

{/* <!-- chunk:2 --> */}

type message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

type requestBody struct {
	Model     string    `json:"model"`
	MaxTokens int       `json:"max_tokens"`
	Messages  []message `json:"messages"`
}

A função serializa o corpo e cria POST /v1/messages. Ela devolve erro de JSON ou request em vez de esconder uma requisição parcial.

{/* <!-- chunk:3 --> */}

func buildRequest(key string, body requestBody) (*http.Request, error) {
	data, err := json.Marshal(body)
	if err != nil {
		return nil, err
	}
	request, err := http.NewRequest(
		"POST", "https://api.anthropic.com/v1/messages", bytes.NewReader(data),
	)
	if err != nil {
		return nil, err
	}