Citações

Claude é capaz de fornecer citações detalhadas ao responder perguntas sobre documentos, ajudando você a rastrear e verificar fontes de informações em 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-opus-4-6",
    "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?"
          }
        ]
      }
    ]
  }'

Como as citações funcionam

Integre citações com Claude nestas etapas:

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

• O 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 serã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

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

Custos de token

• Ativar citações incorre em um ligeiro aumento nos tokens de entrada devido a adições de prompt do sistema e chunking de documento.
• No entanto, o recurso de citações é muito eficiente com tokens de saída. Nos bastidores, o modelo está gerando 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 novamente em voltas de conversa subsequentes, cited_text também não é contado para tokens de entrada.

Compatibilidade de recursos

As citações funcionam em conjunto com outros recursos da API, incluindo prompt caching, contagem de tokens e processamento em lote.

Usando Prompt Caching com Citações

Citações e prompt caching podem ser usadas juntas efetivamente.

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

import anthropic

client = anthropic.Anthropic()

# Long document content (e.g., technical documentation)
long_document = "This is a very long document with thousands of words..." + " ... " * 1000  # Minimum cacheable length

response = client.messages.create(
    model="claude-opus-4-6",
    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"}  # Cache the document content
                },
                {
                    "type": "text",
                    "text": "What does this document say about API features?"
                }
            ]
        }
    ]
)

Neste exemplo:

• O conteúdo do documento é armazenado em cache usando cache_control no bloco de documento
• As citações são ativadas no documento
• Claude pode gerar respostas com citações enquanto se beneficia do conteúdo do documento armazenado em cache
• Solicitações subsequentes usando o mesmo documento se beneficiarão do conteúdo armazenado em cache

Tipos de Documento

Escolhendo um tipo de documento

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

Documentos de texto simples

Documentos de texto simples são automaticamente divididos 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 PDF é extraído e dividido 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 lhe dão controle sobre a granularidade de citação. Nenhum chunking adicional é feito e os chunks são fornecidos ao modelo de acordo com os blocos de conteúdo fornecidos.

{
    "type": "document",
    "source": {
        "type": "content",
        "content": [
            {"type": "text", "text": "First chunk"},
            {"type": "text", "text": "Second chunk"}
        ]
    },
    "title": "Document Title", # optional
    "context": "Context about the document that will not be cited from", # optional
    "citations": {"enabled": True}
}

Estrutura de Resposta

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

{
    "content": [
        {
            "type": "text",
            "text": "According to the document, "
        },
        {
            "type": "text",
            "text": "the grass is green",
            "citations": [{
                "type": "char_location",
                "cited_text": "The grass is green.",
                "document_index": 0,
                "document_title": "Example Document",
                "start_char_index": 0,
                "end_char_index": 20
            }]
        },
        {
            "type": "text",
            "text": " and "
        },
        {
            "type": "text",
            "text": "the sky is blue",
            "citations": [{
                "type": "char_location",
                "cited_text": "The sky is blue.",
                "document_index": 0,
                "document_title": "Example Document",
                "start_char_index": 20,
                "end_char_index": 36
            }]
        },
        {
            "type": "text",
            "text": ". Information from page 5 states that ",
        },
        {
            "type": "text",
            "text": "water is essential",
            "citations": [{
                "type": "page_location",
                "cited_text": "Water is essential for life.",
                "document_index": 1,
                "document_title": "PDF Document",
                "start_page_number": 5,
                "end_page_number": 6
            }]
        },
        {
            "type": "text",
            "text": ". The custom document mentions ",
        },
        {
            "type": "text",
            "text": "important findings",
            "citations": [{
                "type": "content_block_location",
                "cited_text": "These are important findings.",
                "document_index": 2,
                "document_title": "Custom Content Document",
                "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 a ser adicionada à lista citations no bloco de conteúdo de texto atual.