Citações

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

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

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

Compartilhe seus comentários e sugestões sobre o recurso de citações usando este formulário.

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

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?"
          }
        ]
      }
    ]
  }'

Comparação com abordagens baseadas em prompts

Em comparação com soluções de citações baseadas em prompts, o recurso de citações tem as seguintes vantagens:

Economia de custos: Se sua abordagem baseada em prompts pedir ao Claude para gerar citações diretas, você pode ver economia de custos devido ao fato de que cited_text não conta para seus tokens de saída.
Melhor confiabilidade de citações: Como as citações são analisadas nos respectivos formatos de resposta mencionados acima e cited_text é extraído, as citações são garantidas de conter ponteiros válidos para os documentos fornecidos.
Qualidade de citação melhorada: Em avaliações, o recurso de citações foi considerado significativamente mais provável de citar as citações mais relevantes de documentos em comparação com abordagens puramente baseadas em prompts.

Como as citações funcionam

Integre citações com Claude nestas etapas:

Chunking automático vs conteúdo personalizado

Por padrão, documentos de texto simples e PDF são automaticamente divididos em sentenças. Se você precisar de mais controle sobre a granularidade de citação (por exemplo, para pontos de bala ou transcrições), use documentos de conteúdo personalizado. Veja Tipos de Documento para mais detalhes.

Por exemplo, se você quiser que Claude seja capaz de citar sentenças específicas de seus chunks de RAG, você deve colocar cada chunk de RAG em um documento de texto simples. Caso contrário, se você não quiser nenhuma divisão adicional a ser feita, ou se quiser personalizar qualquer divisão adicional, você pode colocar chunks de RAG em documento(s) de conteúdo personalizado.

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 usados para conteúdo citado.
title é limitado em comprimento, portanto 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 finais exclusivos.
Os números de página são indexados em 1 com números de página finais exclusivos.
Os índices de blocos 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

Ativar citações incorre em um leve 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 de volta em turnos 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 cache de prompts, contagem de tokens e processamento em lote.

Citações e Saídas Estruturadas são incompatíveis

As citações não podem ser usadas junto com Saídas Estruturadas. Se você ativar citações em qualquer documento fornecido pelo usuário (blocos de Documento ou RequestSearchResultBlock) e também incluir o parâmetro output_config.format (ou o parâmetro output_format descontinuado), a API retornará um erro 400.

Isso ocorre porque as citações exigem intercalação de blocos de citação com saída de texto, o que é incompatível com as restrições de esquema JSON rigorosas de saídas estruturadas.

Usando Cache de Prompts com Citações

Citações e cache de prompts podem ser usados juntos 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.

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 em cache
Solicitações subsequentes usando o mesmo documento se beneficiarão 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 carregados via API de Arquivos e referenciados por file_id:

Tipo	Melhor para	Chunking	Formato de citação
Texto simples	Documentos de texto simples, prosa	Sentença	Índices de caracteres (indexado em 0)
PDF	Arquivos PDF com conteúdo de texto	Sentença	Números de página (indexado em 1)
Conteúdo personalizado	Listas, transcrições, formatação especial, citações mais granulares	Sem chunking adicional	Índices de blocos (indexado em 0)

Arquivos .csv, .xlsx, .docx, .md e .txt não são suportados como blocos de documento. Converta-os para texto simples e inclua diretamente no conteúdo da mensagem. Veja Trabalhando com outros formatos de arquivo.

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 do 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 estão ativadas, 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 de streaming, um tipo citations_delta é incluído que contém uma única citação a ser adicionada à lista citations no bloco de conteúdo text atual.

Forneça documento(s) e ative 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 de seus documentos. Atualmente, as citações devem ser ativadas em todos ou nenhum dos documentos dentro de uma solicitação.
- Observe que apenas citações de texto são atualmente suportadas e citações de imagem ainda não são possíveis.
Documentos são processados
- O conteúdo do documento é "dividido em chunks" para definir a granularidade mínima de possíveis citações. Por exemplo, a divisão em sentenças permitiria ao Claude citar uma única sentença ou encadear várias sentenças consecutivas para citar um parágrafo (ou mais)!
  - Para PDFs: O texto é extraído conforme descrito em Suporte a PDF e o conteúdo é dividido em sentenças. Citar imagens de PDFs não é atualmente suportado.
  - Para documentos de texto simples: O conteúdo é dividido em sentenças que podem ser citadas.
  - Para documentos de conteúdo personalizado: Seus blocos de conteúdo fornecidos são usados como estão e nenhuma divisão adicional é feita.
Claude fornece resposta citada
- 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 apoiam a afirmação.
- As citações fazem referência a locais específicos em documentos de origem. O formato dessas citações depende do tipo de documento sendo citado.
  - Para PDFs: As citações incluem o intervalo de números de página (indexado em 1).
  - Para documentos de texto simples: As citações incluem o intervalo de índices de caracteres (indexado em 0).
  - Para documentos de conteúdo personalizado: As citações incluem o intervalo de índices de blocos de conteúdo (indexado em 0) correspondendo à lista de conteúdo original fornecida.
- Os índices de documento são fornecidos para indicar a fonte de referência e são indexados em 0 de acordo com a lista de todos os documentos em sua solicitação original.

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "text",
                        "media_type": "text/plain",
                        "data": "This is a very long document with thousands of words..."
                    },
                    "citations": {"enabled": true},
                    "cache_control": {"type": "ephemeral"}
                },
                {
                    "type": "text",
                    "text": "What does this document say about API features?"
                }
            ]
        }
    ]
}'

Como as citações funcionam

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

Índices de citação

Custos de token

Compatibilidade de recursos

Usando Cache de Prompts com Citações

Tipos de Documento

Escolhendo um tipo de documento

Documentos de texto simples

Exemplo de citação de texto simples

Documentos PDF

Exemplo de citação de PDF

Documentos de conteúdo personalizado

Exemplo de citação

Estrutura de Resposta

Suporte a Streaming

Exemplo de eventos de streaming