Citações

Claude é capaz de fornecer citações detalhadas ao responder perguntas sobre documentos, ajudando você a rastrear e verificar fontes de informação nas respostas.

Todos os modelos ativos suportam citações, com exceção do Haiku 3.

Aqui está um exemplo de como usar citações com a API Messages:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "document",
            "source": {
              "type": "text",
              "media_type": "text/plain",
              "data": "The grass is green. The sky is blue."
            },
            "title": "My Document",
            "context": "This is a trustworthy document.",
            "citations": {"enabled": true}
          },
          {
            "type": "text",
            "text": "What color is the grass and sky?"
          }
        ]
      }
    ]
  }'

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "text",
                        "media_type": "text/plain",
                        "data": "The grass is green. The sky is blue."
                    },
                    "title": "My Document",
                    "context": "This is a trustworthy document.",
                    "citations": {"enabled": True}
                },
                {
                    "type": "text",
                    "text": "What color is the grass and sky?"
                }
            ]
        }
    ]
)
print(response)

import java.util.List;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.*;

public class DocumentExample {

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        PlainTextSource source = PlainTextSource.builder()
                .data("The grass is green. The sky is blue.")
                .build();

        DocumentBlockParam documentParam = DocumentBlockParam.builder()
                .source(source)
                .title("My Document")
                .context("This is a trustworthy document.")
                .citations(CitationsConfigParam.builder().enabled(true).build())
                .build();
        
        TextBlockParam textBlockParam = TextBlockParam.builder()
                .text("What color is the grass and sky?")
                .build();

        MessageCreateParams params = MessageCreateParams.builder()
                .model(Model.CLAUDE_SONNET_4_20250514)
                .maxTokens(1024)
                .addUserMessageOfBlockParams(List.of(ContentBlockParam.ofDocument(documentParam), ContentBlockParam.ofText(textBlockParam)))
                .build();

        Message message = client.messages().create(params);
        System.out.println(message);
    }
}

Como as citações funcionam

Integre citações com Claude nestes passos:

Conteúdo citável vs não citável

• Texto encontrado dentro do conteúdo source de um documento pode ser citado.
• title e context são campos opcionais que serão passados para o modelo mas não usados para conteúdo citado.
• title é limitado em comprimento então você pode achar o campo context útil para armazenar qualquer metadado de documento como texto ou json stringificado.

Índices de citação

• Índices de documento são indexados em 0 da lista de todos os blocos de conteúdo de documento na solicitação (abrangendo todas as mensagens).
• Índices de caracteres são indexados em 0 com índices finais exclusivos.
• Números de página são indexados em 1 com números de página finais exclusivos.
• Índices de bloco de conteúdo são indexados em 0 com índices finais exclusivos da lista content fornecida no documento de conteúdo personalizado.

Custos de token

• Habilitar citações incorre em um ligeiro aumento nos tokens de entrada devido a adições de prompt do sistema e fragmentação de documento.
• No entanto, o recurso de citações é muito eficiente com tokens de saída. Por baixo dos panos, o modelo está produzindo citações em um formato padronizado que são então analisadas em texto citado e índices de localização de documento. O campo cited_text é fornecido por conveniência e não conta para tokens de saída.
• Quando passado de volta em turnos de conversa subsequentes, cited_text também não é contado para tokens de entrada.

Compatibilidade de recursos

Citações funciona em conjunto com outros recursos da API incluindo cache de prompt, contagem de tokens e processamento em lote.

Usando Cache de Prompt com Citações

Citações e cache de prompt podem ser usados juntos efetivamente.

Os blocos de citação gerados nas respostas não podem ser cacheados diretamente, mas os documentos fonte que eles referenciam podem ser cacheados. Para otimizar o desempenho, aplique cache_control aos seus blocos de conteúdo de documento de nível superior.

import anthropic

client = anthropic.Anthropic()

# Conteúdo de documento longo (por exemplo, documentação técnica)
long_document = "Este é um documento muito longo com milhares de palavras..." + " ... " * 1000  # Comprimento mínimo cacheável

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "text",
                        "media_type": "text/plain",
                        "data": long_document
                    },
                    "citations": {"enabled": True},
                    "cache_control": {"type": "ephemeral"}  # Cachear o conteúdo do documento
                },
                {
                    "type": "text",
                    "text": "O que este documento diz sobre recursos da API?"
                }
            ]
        }
    ]
)

Neste exemplo:

• O conteúdo do documento é cacheado usando cache_control no bloco do documento
• Citações são habilitadas no documento
• Claude pode gerar respostas com citações enquanto se beneficia do conteúdo do documento cacheado
• Solicitações subsequentes usando o mesmo documento se beneficiarão do conteúdo cacheado

Tipos de Documento

Escolhendo um tipo de documento

Suportamos três tipos de documento para citações. Documentos podem ser fornecidos diretamente na mensagem (base64, texto, ou URL) ou carregados via API Files e referenciados por file_id:

Documentos de texto simples

Documentos de texto simples são automaticamente fragmentados em sentenças. Você pode fornecê-los inline ou por referência com seu file_id:

Documentos PDF

Documentos PDF podem ser fornecidos como dados codificados em base64 ou por file_id. O texto do PDF é extraído e fragmentado em sentenças. Como citações de imagem ainda não são suportadas, PDFs que são digitalizações de documentos e não contêm texto extraível não serão citáveis.

Documentos de conteúdo personalizado

Documentos de conteúdo personalizado dão a você controle sobre a granularidade de citação. Nenhuma fragmentação adicional é feita e fragmentos são fornecidos ao modelo de acordo com os blocos de conteúdo fornecidos.

{
    "type": "document",
    "source": {
        "type": "content",
        "content": [
            {"type": "text", "text": "Primeiro fragmento"},
            {"type": "text", "text": "Segundo fragmento"}
        ]
    },
    "title": "Título do Documento", # opcional
    "context": "Contexto sobre o documento que não será citado", # opcional
    "citations": {"enabled": True}
}

Estrutura de Resposta

Quando citações são habilitadas, as respostas incluem múltiplos blocos de texto com citações:

{
    "content": [
        {
            "type": "text",
            "text": "De acordo com o documento, "
        },
        {
            "type": "text",
            "text": "a grama é verde",
            "citations": [{
                "type": "char_location",
                "cited_text": "A grama é verde.",
                "document_index": 0,
                "document_title": "Documento de Exemplo",
                "start_char_index": 0,
                "end_char_index": 20
            }]
        },
        {
            "type": "text",
            "text": " e "
        },
        {
            "type": "text",
            "text": "o céu é azul",
            "citations": [{
                "type": "char_location",
                "cited_text": "O céu é azul.",
                "document_index": 0,
                "document_title": "Documento de Exemplo",
                "start_char_index": 20,
                "end_char_index": 36
            }]
        },
        {
            "type": "text",
            "text": ". Informação da página 5 afirma que ",
        },
        {
            "type": "text",
            "text": "água é essencial",
            "citations": [{
                "type": "page_location",
                "cited_text": "Água é essencial para a vida.",
                "document_index": 1,
                "document_title": "Documento PDF",
                "start_page_number": 5,
                "end_page_number": 6
            }]
        },
        {
            "type": "text",
            "text": ". O documento personalizado menciona ",
        },
        {
            "type": "text",
            "text": "descobertas importantes",
            "citations": [{
                "type": "content_block_location",
                "cited_text": "Estas são descobertas importantes.",
                "document_index": 2,
                "document_title": "Documento de Conteúdo Personalizado",
                "start_block_index": 0,
                "end_block_index": 1
            }]
        }
    ]
}

Suporte a Streaming

Para respostas de streaming, adicionamos um tipo citations_delta que contém uma única citação para ser adicionada à lista citations no bloco de conteúdo text atual.