Citas

Claude puede proporcionar citas detalladas al responder preguntas sobre documentos, ayudándote a rastrear y verificar las fuentes detrás de cada respuesta.

Todos los modelos activos admiten citas.

El siguiente ejemplo muestra cómo habilitar citas en un documento de texto plano con la Messages API:

client = anthropic.Anthropic()

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



Cómo funcionan las citas

Integra las citas con Claude siguiendo estos pasos:



Contenido citable versus no citable

• El texto que se encuentra dentro del contenido source de un documento puede citarse.
• title y context son campos opcionales que se pasan al modelo pero no se usan como contenido citable.
• title tiene una longitud limitada, por lo que el campo context es útil para almacenar metadatos del documento como texto o JSON convertido a cadena.



Índices de citas

• Los índices de documentos están indexados desde 0 a partir 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 a partir de la lista content proporcionada en el documento de contenido personalizado.



Costos de tokens

• Habilitar las citas implica un ligero aumento en los tokens de entrada debido a las adiciones a la indicación del sistema y la división de documentos.
• Sin embargo, la función de citas es muy eficiente con los tokens de salida. Internamente, el modelo genera citas en un formato estandarizado que luego se analizan en texto citado e índices de ubicación del documento. El campo cited_text se proporciona por conveniencia y no cuenta para los tokens de salida.
• Cuando se devuelve en turnos de conversación posteriores, cited_text tampoco cuenta para los tokens de entrada.



Compatibilidad de funciones

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



Uso del almacenamiento en caché de prompts con citas

Las citas y el almacenamiento en caché de prompts pueden usarse juntos de manera efectiva.

Los bloques de citas generados en las respuestas no pueden almacenarse en caché directamente, pero los documentos fuente a los que hacen referencia sí pueden almacenarse en caché. Para optimizar el rendimiento, aplica cache_control a tus bloques de contenido de documentos de nivel superior.

client = anthropic.Anthropic()

# Contenido de documento largo (por ejemplo, documentación 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",
    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)

En este ejemplo:

• El contenido del documento se almacena en caché 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 almacenado en caché.
• Las solicitudes posteriores que usen el mismo documento se benefician del contenido almacenado en caché.



Tipos de documentos



Elegir un tipo de documento

Se admiten tres tipos de documentos para las citas. Los documentos pueden proporcionarse directamente en el mensaje (base64, texto o URL) o cargarse a través de la Files API y referenciarse mediante file_id:



Documentos de texto plano

Los documentos de texto plano se dividen automáticamente en oraciones. Puedes proporcionarlos en línea o por referencia con su 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 }
}



Documentos PDF

Los documentos PDF pueden proporcionarse como datos codificados en base64, una URL o mediante file_id. El texto del PDF se extrae y se divide en oraciones. Como las citas de imágenes aún no son compatibles, los PDFs que son escaneos de documentos y no contienen texto extraíble no son citables.

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",
    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)



Documentos de contenido personalizado

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

client = anthropic.Anthropic()

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



Estructura de la respuesta

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

{
    "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,
                }
            ],
        },
    ]
}



Soporte de streaming

Para respuestas en streaming, las citas llegan como un tipo de delta citations_delta dentro de eventos content_block_delta. Cada delta contiene una sola cita para agregar a la lista citations en el bloque de contenido text actual.



Próximos pasos