Citações

Claude pode fornecer citações detalhadas ao responder perguntas sobre documentos, ajudando você a rastrear e verificar as fontes por trás de cada resposta.

Todos os modelos ativos suportam citações.

O exemplo a seguir mostra como habilitar citações em um documento de texto simples com a Messages API:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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)

Como as citações funcionam

Integre citações com Claude nestas etapas:

1. 1

   Forneça documento(s) e habilite citações

   • Inclua documentos em qualquer um dos formatos suportados: documentos PDFs, texto simples ou conteúdo personalizado.
   • Defina citations.enabled=true em cada um dos seus documentos. Atualmente, as citações devem ser habilitadas em todos ou em nenhum dos documentos dentro de uma requisição.
   • Apenas citações de texto são suportadas atualmente. Citações de imagem ainda não são possíveis.
2. 2

   Os documentos são processados

   • O conteúdo dos documentos é "fragmentado" (chunked) para definir a granularidade mínima das citações possíveis. Por exemplo, a fragmentação por sentença permite que Claude cite uma única sentença ou encadeie várias sentenças consecutivas para citar um parágrafo ou passagem mais longa.
     • Para PDFs: O texto é extraído conforme descrito em suporte a PDF e o conteúdo é fragmentado em sentenças. Citar imagens de PDFs não é suportado atualmente.
     • Para documentos de texto simples: O conteúdo é fragmentado em sentenças que podem ser citadas.
     • Para documentos de conteúdo personalizado: Os blocos de conteúdo fornecidos por você são usados como estão e nenhuma fragmentação adicional é feita.
3. 3

   Claude fornece resposta com citações

   • As respostas agora podem incluir vários blocos de texto, onde cada bloco de texto pode conter uma afirmação que Claude está fazendo e uma lista de citações que sustentam a afirmação.
   • As citações referenciam localizações específicas nos documentos de origem. O formato dessas citações depende do tipo de documento que está sendo citado.
     • Para PDFs: As citações incluem o intervalo de números de página (indexado a partir de 1).
     • Para documentos de texto simples: As citações incluem o intervalo de índices de caracteres (indexado a partir de 0).
     • Para documentos de conteúdo personalizado: As citações incluem o intervalo de índices de blocos de conteúdo (indexado a partir de 0) correspondente à lista de conteúdo original fornecida.
   • Os índices de documentos são fornecidos para indicar a fonte de referência e são indexados a partir de 0 de acordo com a lista de todos os documentos em sua requisição original.

Conteúdo citável versus 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 são passados ao modelo, mas não são usados para o conteúdo citado.
• title é limitado em comprimento, então o campo context é útil para armazenar metadados do documento como texto ou JSON em formato de string.

Índices de citação

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

Custos de tokens

• Habilitar citações incorre em um leve aumento nos tokens de entrada devido a adições ao prompt do sistema e à fragmentação de documentos.
• No entanto, o recurso de citações é muito eficiente com tokens de saída. Internamente, o modelo produz 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 os tokens de saída.
• Quando passado de volta em turnos subsequentes da conversa, cited_text também não é contado para os tokens de entrada.

Compatibilidade de recursos

As citações funcionam 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 de forma eficaz.

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

client = anthropic.Anthropic()

# Conteúdo de documento longo (por exemplo, documentação técnica)
long_document = (
    "This is a very long document with thousands of words..." + " ... " * 1000
)  # Minimum cacheable length

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

Neste exemplo:

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

Tipos de documento

Escolhendo um tipo de documento

Três tipos de documento são suportados para citações. Os documentos podem ser fornecidos diretamente na mensagem (base64, texto ou URL) ou enviados através da Files API 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:

{
  "type": "document",
  "source": {
    "type": "text",
    "media_type": "text/plain",
    "data": "Plain text content..."
  },
  "title": "Document Title",
  "context": "Context about the document that will not be cited from",
  "citations": { "enabled": true }
}

{
  "type": "char_location",
  "cited_text": "The exact text being cited", // not counted toward output tokens
  "document_index": 0,
  "document_title": "Document Title",
  "start_char_index": 0, // 0-indexed
  "end_char_index": 50 // exclusive
}

Documentos PDF

Documentos PDF podem ser fornecidos como dados codificados em base64, uma URL 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 são citáveis.

client = anthropic.Anthropic()

pdf_base64 = base64.standard_b64encode(
    pathlib.Path("/path/to/document.pdf").read_bytes()
).decode()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_base64,
                    },
                    "title": "Document Title",
                    "context": "Context about the document that will not be cited from",
                    "citations": {"enabled": True},
                },
                {"type": "text", "text": "Summarize this document."},
            ],
        }
    ],
)
print(response)

{
  "type": "page_location",
  "cited_text": "The exact text being cited", // not counted toward output tokens
  "document_index": 0,
  "document_title": "Document Title",
  "start_page_number": 1, // 1-indexed
  "end_page_number": 2 // exclusive
}

Documentos de conteúdo personalizado

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "content",
                        "content": [
                            {"type": "text", "text": "First chunk"},
                            {"type": "text", "text": "Second chunk"},
                        ],
                    },
                    "title": "Document Title",
                    "context": "Context about the document that will not be cited from",
                    "citations": {"enabled": True},
                },
                {"type": "text", "text": "Summarize this document."},
            ],
        }
    ],
)
print(response)

{
  "type": "content_block_location",
  "cited_text": "The exact text being cited", // not counted toward output tokens
  "document_index": 0,
  "document_title": "Document Title",
  "start_block_index": 0, // 0-indexed
  "end_block_index": 1 // exclusive
}

Estrutura da resposta

Quando as citações estão habilitadas, as respostas incluem vários 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 em streaming, as citações chegam como um tipo de delta citations_delta dentro de eventos content_block_delta. Cada delta contém uma única citação para adicionar à lista citations no bloco de conteúdo text atual.

event: message_start
data: {"type": "message_start", ...}

event: content_block_start
data: {"type": "content_block_start", "index": 0, ...}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0,
       "delta": {"type": "text_delta", "text": "According to..."}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0,
       "delta": {"type": "citations_delta",
                 "citation": {
                     "type": "char_location",
                     "cited_text": "...",
                     "document_index": 0,
                     ...
                 }}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_stop
data: {"type": "message_stop"}

Próximos passos

Compatibility