Citas

Claude es capaz de proporcionar citas detalladas al responder preguntas sobre documentos, ayudándote a rastrear y verificar las fuentes de información en las respuestas.

Todos los modelos activos admiten citas, con la excepción de Haiku 3.

Aquí tienes un ejemplo de cómo usar citas con la API de 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);
    }
}

Cómo funcionan las citas

Integra las citas con Claude en estos pasos:

Contenido citable vs no citable

• El texto encontrado dentro del contenido source de un documento puede ser citado.
• title y context son campos opcionales que se pasarán al modelo pero no se usarán hacia el contenido citado.
• title tiene una longitud limitada, por lo que puedes encontrar útil el campo context para almacenar cualquier metadato del documento como texto o json stringificado.

Índices de citas

• Los índices de documentos están indexados desde 0 de la lista de todos los bloques de contenido de documentos en la solicitud (abarcando todos los mensajes).
• Los índices de caracteres están indexados desde 0 con índices finales exclusivos.
• Los números de página están indexados desde 1 con números de página finales exclusivos.
• Los índices de bloques de contenido están indexados desde 0 con índices finales exclusivos de la lista content proporcionada en el documento de contenido personalizado.

Costos de tokens

• Habilitar citas incurre en un ligero aumento en los tokens de entrada debido a las adiciones del prompt del sistema y la fragmentación de documentos.
• Sin embargo, la función de citas es muy eficiente con los tokens de salida. Internamente, el modelo está produciendo citas en un formato estandarizado que luego se analizan en texto citado e índices de ubicación de documentos. El campo cited_text se proporciona por conveniencia y no cuenta hacia los tokens de salida.
• Cuando se pasa de vuelta en turnos de conversación posteriores, cited_text tampoco se cuenta hacia los tokens de entrada.

Compatibilidad de funciones

Las citas funcionan en conjunto con otras funciones de la API incluyendo caché de prompts, conteo de tokens y procesamiento por lotes.

Usar Caché de Prompts con Citas

Las citas y el caché de prompts se pueden usar juntos de manera efectiva.

Los bloques de citas generados en las respuestas no se pueden cachear directamente, pero los documentos fuente que referencian sí se pueden cachear. Para optimizar el rendimiento, aplica cache_control a tus bloques de contenido de documentos de nivel superior.

import anthropic

client = anthropic.Anthropic()

# Contenido de documento largo (por ejemplo, documentación técnica)
long_document = "Este es un documento muy largo con miles de palabras..." + " ... " * 1000  # Longitud mínima cacheable

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 el contenido del documento
                },
                {
                    "type": "text",
                    "text": "¿Qué dice este documento sobre las funciones de la API?"
                }
            ]
        }
    ]
)

En este ejemplo:

• El contenido del documento se cachea usando cache_control en el bloque del documento
• Las citas están habilitadas en el documento
• Claude puede generar respuestas con citas mientras se beneficia del contenido del documento cacheado
• Las solicitudes posteriores usando el mismo documento se beneficiarán del contenido cacheado

Tipos de Documentos

Elegir un tipo de documento

Admitimos tres tipos de documentos para citas. Los documentos se pueden proporcionar directamente en el mensaje (base64, texto o URL) o subir a través de la API de Files y referenciar por file_id:

Documentos de texto plano

Los documentos de texto plano se fragmentan automáticamente en oraciones. Puedes proporcionarlos en línea o por referencia con su file_id:

Documentos PDF

Los documentos PDF se pueden proporcionar como datos codificados en base64 o por file_id. El texto del PDF se extrae y se fragmenta en oraciones. Como las citas de imágenes aún no están soportadas, los PDFs que son escaneos de documentos y no contienen texto extraíble no serán citables.

Documentos de contenido personalizado

Los documentos de contenido personalizado te dan control sobre la granularidad de las citas. No se hace fragmentación adicional y los fragmentos se proporcionan al modelo según los bloques de contenido proporcionados.

{
    "type": "document",
    "source": {
        "type": "content",
        "content": [
            {"type": "text", "text": "Primer fragmento"},
            {"type": "text", "text": "Segundo fragmento"}
        ]
    },
    "title": "Título del Documento", # opcional
    "context": "Contexto sobre el documento del que no se citará", # opcional
    "citations": {"enabled": True}
}

Estructura de Respuesta

Cuando las citas están habilitadas, las respuestas incluyen múltiples bloques de texto con citas:

{
    "content": [
        {
            "type": "text",
            "text": "Según el documento, "
        },
        {
            "type": "text",
            "text": "la hierba es verde",
            "citations": [{
                "type": "char_location",
                "cited_text": "La hierba es verde.",
                "document_index": 0,
                "document_title": "Documento de Ejemplo",
                "start_char_index": 0,
                "end_char_index": 20
            }]
        },
        {
            "type": "text",
            "text": " y "
        },
        {
            "type": "text",
            "text": "el cielo es azul",
            "citations": [{
                "type": "char_location",
                "cited_text": "El cielo es azul.",
                "document_index": 0,
                "document_title": "Documento de Ejemplo",
                "start_char_index": 20,
                "end_char_index": 36
            }]
        },
        {
            "type": "text",
            "text": ". La información de la página 5 establece que ",
        },
        {
            "type": "text",
            "text": "el agua es esencial",
            "citations": [{
                "type": "page_location",
                "cited_text": "El agua es esencial para la vida.",
                "document_index": 1,
                "document_title": "Documento PDF",
                "start_page_number": 5,
                "end_page_number": 6
            }]
        },
        {
            "type": "text",
            "text": ". El documento personalizado menciona ",
        },
        {
            "type": "text",
            "text": "hallazgos importantes",
            "citations": [{
                "type": "content_block_location",
                "cited_text": "Estos son hallazgos importantes.",
                "document_index": 2,
                "document_title": "Documento de Contenido Personalizado",
                "start_block_index": 0,
                "end_block_index": 1
            }]
        }
    ]
}

Soporte de Streaming

Para respuestas de streaming, hemos agregado un tipo citations_delta que contiene una sola cita para ser agregada a la lista citations en el bloque de contenido text actual.