---
title: Files API
url: https://platform.claude.com/docs/es/build-with-claude/files
description: Sube archivos una vez, haz referencia a ellos mediante file_id en las solicitudes de Messages y descarga los resultados creados por skills o la herramienta de ejecución de código.
featureMetadata:
status: stable
zdr:
eligibility: not-eligible
note: Los archivos se conservan hasta que se eliminan explícitamente o alcanzan su vencimiento configurado.
supportedModels:
- claude-fable-5-2
- claude-mythos-5-2
- claude-fable-5-1
- claude-mythos-5-1
- claude-fable-5
- claude-mythos-5
- claude-mythos-preview
- claude-opus-5-5
- claude-opus-5
- claude-sonnet-5-5
- claude-sonnet-5
- claude-haiku-5-5
- claude-haiku-4-5-20251001
- claude-opus-4-8
- claude-opus-4-7
- claude-opus-4-6
- claude-sonnet-4-6
- claude-opus-4-5-20251101
- claude-sonnet-4-5-20250929
supportedPlatforms:
Claude API: stable
Claude Platform on AWS: stable
Claude Models on Google Cloud (Anthropic managed): stable
Microsoft Foundry (hosted on Anthropic): stable
---
**Compatibilidad con la API**: El uso varía según el producto.
* **Messages API**: Haz referencia a un archivo subido mediante su `file_id` en un bloque `document`, `image` o `container_upload`.
* **Managed Agents**: Monta archivos en el sandbox de la sesión o haz referencia a un `file_id` en un evento `user.message`.
La Files API te permite subir y administrar archivos para usarlos con la Claude API sin volver a subir el contenido con cada solicitud. Esto es particularmente útil cuando usas la [herramienta de ejecución de código](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool) para proporcionar entradas (por ejemplo, conjuntos de datos y documentos) y luego descargar salidas (por ejemplo, gráficos). Puedes [explorar la referencia de la API directamente](https://platform.claude.com/docs/es/api/files/upload), además de esta guía.
## Compatibilidad de tipos de archivo
Hacer referencia a un `file_id` en una solicitud de Messages es compatible con todos los modelos que admiten el tipo de archivo dado. Las [imágenes](https://platform.claude.com/docs/es/build-with-claude/vision) son compatibles con todos los modelos actuales de Claude. Para [PDFs](https://platform.claude.com/docs/es/build-with-claude/pdf-support) y [otros tipos de archivo con la herramienta de ejecución de código](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#availability-feature-support), consulta las páginas enlazadas para conocer la compatibilidad de modelos.
## Cómo funciona la Files API
La Files API proporciona un enfoque de crear una vez y usar muchas veces para trabajar con archivos:
* **Sube archivos** al almacenamiento seguro de Anthropic y recibe un `file_id` único
* **Descarga archivos** creados por skills o la herramienta de ejecución de código
* **Haz referencia a archivos** en solicitudes de [Messages](https://platform.claude.com/docs/es/api/messages/create) usando el `file_id` en lugar de volver a subir el contenido
* **Administra tus archivos** con operaciones de listar, recuperar y eliminar
Los archivos no están limitados a un usuario final, una conversación o una sesión. Cualquier clave de API con acceso a un espacio de trabajo puede acceder a cualquier archivo subido a ese espacio de trabajo. Cada cuenta de servicio, y cada usuario cuyo rol en la organización permita el acceso a la API, puede usar el espacio de trabajo predeterminado además de cualquier espacio de trabajo al que lo agregues, así que mantén los archivos que deban permanecer separados en su propio espacio de trabajo y accede a ellos solo con [claves limitadas a ese espacio de trabajo](https://platform.claude.com/docs/es/manage-claude/workspaces#api-keys-and-resource-scoping). Nunca aceptes valores de `file_id` de usuarios finales u otras fuentes no confiables: un ID de archivo proporcionado por un usuario permitiría que un usuario de tu aplicación lea contenido que otro usuario subió. Trata los ID de archivo como referencias del lado del servidor y mantén la correspondencia entre tus usuarios y sus archivos en tu aplicación.
Si estás creando una aplicación multiinquilino sobre la Files API, crea un [espacio de trabajo](https://platform.claude.com/docs/es/manage-claude/workspaces) independiente para cada inquilino. El espacio de trabajo es el límite de aislamiento de los archivos, por lo que un espacio de trabajo para cada inquilino proporciona a los datos de ese inquilino un aislamiento estricto respecto de todos los demás inquilinos. Cada organización puede tener hasta 100 espacios de trabajo; contacta a tu equipo de cuenta si necesitas más.
## Cómo usar la Files API
### Subir un archivo
Sube un archivo para hacer referencia a él en futuras llamadas a la API:
```bash cURL
curl -X POST https://api.anthropic.com/v1/files \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-F "file=@/path/to/document.pdf"
```
```bash CLI
ant files upload --file /path/to/document.pdf
```
```python Python
uploaded = client.files.upload(
file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id
print(file_id)
```
```typescript TypeScript
const uploaded = await client.files.upload({
file: await toFile(fs.createReadStream("/path/to/document.pdf"), undefined, {
type: "application/pdf"
})
});
console.log(uploaded.id);
```
```csharp C#
var uploaded = await client.Files.Upload(
new FileUploadParams
{
File = new BinaryContent
{
Stream = File.OpenRead("/path/to/document.pdf"),
FileName = "document.pdf",
ContentType = new("application/pdf")
}
});
var fileId = uploaded.ID;
Console.WriteLine(fileId);
```
```go Go
f, err := os.Open("/path/to/document.pdf")
if err != nil {
log.Fatal(err)
}
defer f.Close()
response, err := client.Files.Upload(context.Background(),
anthropic.FileUploadParams{
File: anthropic.File(f, "document.pdf", "application/pdf"),
})
if err != nil {
log.Fatal(err)
}
fileID := response.ID
fmt.Println(fileID)
```
```java Java
FileMetadata file = client.files().upload(
FileUploadParams.builder()
.file(MultipartField.builder()
.value(Files.newInputStream(Path.of("/path/to/document.pdf")))
.filename("document.pdf")
.contentType("application/pdf")
.build())
.build()
);
String fileId = file.id();
System.out.println(fileId);
```
```php PHP
$file = $client->files->upload(
file: FileParam::fromResource(fopen('/path/to/document.pdf', 'rb'), contentType: 'application/pdf'),
);
$fileId = $file->id;
echo $fileId;
```
```ruby Ruby
file = client.files.upload(
file: Anthropic::FilePart.new(
Pathname("/path/to/document.pdf"),
content_type: "application/pdf"
)
)
file_id = file.id
puts file_id
```
La respuesta al subir un archivo incluye:
```json Response
{
"id": "file_011CNha8iCJcU1wXNR6q4V8w",
"type": "file",
"filename": "document.pdf",
"mime_type": "application/pdf",
"size_bytes": 1024000,
"created_at": "2025-01-01T00:00:00Z",
"downloadable": false,
"expires_at": null
}
```
[`downloadable`](https://platform.claude.com/docs/es/api/files#file_metadata.downloadable) es `false` para los archivos que subes. Solo se pueden descargar los archivos creados por [skills](https://platform.claude.com/docs/es/build-with-claude/skills-guide) o por la [herramienta de ejecución de código](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool). Consulta [Descargar un archivo](https://platform.claude.com/docs/es/build-with-claude/files#downloading-a-file).
La referencia de la API describe cada campo del objeto de archivo.
(See `file_metadata` on `files` in [the API reference](https://platform.claude.com/docs/es/api/files#file_metadata).)
### Usar un archivo en mensajes
Una vez subido, haz referencia al archivo pasando el `id` de la respuesta de subida como `file_id`:
```bash cURL
curl -X POST https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Please summarize this document for me."
},
{
"type": "document",
"source": {
"type": "file",
"file_id": "'"$FILE_ID"'"
}
}
]
}
]
}'
```
```bash CLI
ant messages create <
{
new TextBlockParam { Text = "Please summarize this document for me." },
new DocumentBlockParam
{
Source = new FileDocumentSource { FileID = fileId }
}
}
}
]
});
Console.WriteLine(response);
```
```go Go
msg, err := client.Messages.New(context.Background(),
anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(
anthropic.NewTextBlock("Please summarize this document for me."),
anthropic.NewDocumentBlock(anthropic.FileDocumentSourceParam{
FileID: fileID,
}),
),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg)
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addUserMessageOfContentBlockParams(List.of(
ContentBlockParam.ofText(TextBlockParam.builder()
.text("Please summarize this document for me.")
.build()),
ContentBlockParam.ofDocument(DocumentBlockParam.builder()
.fileSource(fileId)
.build())
))
.build();
Message message = client.messages().create(params);
System.out.println(message);
```
```php PHP
$response = $client->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => [
['type' => 'text', 'text' => 'Please summarize this document for me.'],
[
'type' => 'document',
'source' => [
'type' => 'file',
'fileID' => $fileId,
],
],
],
],
],
model: 'claude-opus-5-5',
);
echo $response;
```
```ruby Ruby
response = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
messages: [
{
role: "user",
content: [
{ type: "text", text: "Please summarize this document for me." },
{
type: "document",
source: {
type: "file",
file_id: file_id
}
}
]
}
]
)
puts response
```
### Tipos de archivo y bloques de contenido
La Files API admite diferentes tipos de archivo que corresponden a diferentes tipos de bloques de contenido:
| Tipo de archivo | Tipo MIME | Tipo de bloque de contenido | Caso de uso |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | --------------------------- | ---------------------------------------------- |
| PDF | `application/pdf` | `document` | Análisis de texto, procesamiento de documentos |
| Texto plano | `text/plain` | `document` | Análisis de texto, procesamiento |
| Imágenes | `image/jpeg`, `image/png`, `image/gif`, `image/webp` | `image` | Análisis de imágenes, tareas visuales |
| Conjuntos de datos, otros (consulta [Sube y analiza tus propios archivos](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files)) | Varía | `container_upload` | Análisis de datos, visualización |
#### Bloques de documento
Para PDFs y archivos de texto, usa el bloque de contenido `document`:
```json
{
"type": "document",
"source": {
"type": "file",
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
},
"title": "Document Title", // Optional
"context": "Context about the document", // Optional
"citations": { "enabled": true } // Optional, enables citations
}
```
#### Bloques de imagen
Para imágenes, usa el bloque de contenido `image`:
```json
{
"type": "image",
"source": {
"type": "file",
"file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
}
}
```
#### Bloques de carga a contenedor
Para [enviar un archivo a la herramienta de ejecución de código](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files), usa el bloque de contenido `container_upload`:
```json
{
"type": "container_upload",
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
}
```
### Trabajar con otros formatos de archivo
Para tipos de archivo que el bloque `document` no admite (por ejemplo, .docx y .xlsx), convierte los archivos a texto sin formato e incluye el contenido directamente en tu mensaje. Los archivos que ya son texto sin formato, como los archivos .csv y .md, pueden leerse de esta manera o subirse a través de la Files API con un tipo de contenido `text/plain` explícito. Para analizar conjuntos de datos en lugar de leerlos como texto, súbelos para la herramienta de ejecución de código usando un bloque `container_upload` (consulta [Sube y analiza tus propios archivos](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files)).
Los siguientes ejemplos leen un archivo de texto y envían su contenido como texto plano:
```bash cURL
# Lee el archivo de texto
# Nota: para archivos con caracteres especiales, considera usar codificación base64
TEXT_CONTENT=$(cat document.txt)
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-d @- < block.type === "text");
console.log(textBlock?.text);
```
```csharp C#
AnthropicClient client = new();
// Lee el archivo de texto
string textContent = await File.ReadAllTextAsync("document.txt");
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = [new UserMessageParam
{
Content = $"Here's the document content:\n\n{textContent}\n\nPlease summarize this document."
}]
};
var message = await client.Messages.Create(parameters);
foreach (var block in message.Content)
{
if (block.TryPickText(out var textBlock))
{
Console.WriteLine(textBlock.Text);
}
}
```
```go Go
client := anthropic.NewClient()
// Lee el archivo de texto
textContent, err := os.ReadFile("document.txt")
if err != nil {
log.Fatal(err)
}
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock(
fmt.Sprintf("Here's the document content:\n\n%s\n\nPlease summarize this document.", string(textContent)),
)),
},
})
if err != nil {
log.Fatal(err)
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
fmt.Println(textBlock.Text)
}
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Lee el archivo de texto
String textContent = Files.readString(Path.of("document.txt"));
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessage("Here's the document content:\n\n" + textContent + "\n\nPlease summarize this document.")
.build();
Message response = client.messages().create(params);
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> System.out.println(textBlock.text()));
```
```php PHP
$client = new Client();
// Lee el archivo de texto
$textContent = file_get_contents('document.txt');
$message = $client->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => [
[
'type' => 'text',
'text' => "Here's the document content:\n\n{$textContent}\n\nPlease summarize this document."
]
]
]
],
model: 'claude-opus-5-5',
);
foreach ($message->content as $block) {
if ($block->type === 'text') {
echo $block->text, PHP_EOL;
}
}
```
```ruby Ruby
client = Anthropic::Client.new
# Lee el archivo de texto
text_content = File.read("document.txt")
message = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
messages: [
{
role: "user",
content: [
{
type: "text",
text: "Here's the document content:\n\n#{text_content}\n\nPlease summarize this document."
}
]
}
]
)
message.content.each do |block|
puts block.text if block.type == :text
end
```
Para archivos .docx que contienen imágenes, conviértelos primero a formato PDF y luego usa la [compatibilidad con PDF](https://platform.claude.com/docs/es/build-with-claude/pdf-support) para aprovechar el análisis de imágenes integrado. Esto permite usar citas del documento PDF.
### Administrar archivos
#### Listar archivos
Obtén una lista de tus archivos subidos. El endpoint está paginado: cada solicitud devuelve hasta [`limit`](https://platform.claude.com/docs/es/api/files/list#list.limit) archivos (20 de forma predeterminada y como máximo 1,000), y el cursor [`next_page`](https://platform.claude.com/docs/es/api/files/list#list.response.next_page) de la respuesta obtiene la página siguiente cuando lo pasas de vuelta como el parámetro [`page`](https://platform.claude.com/docs/es/api/files/list#list.page). Los archivos se ordenan del más reciente al más antiguo. Consulta la [referencia de la API Listar archivos](https://platform.claude.com/docs/es/api/files/list). El SDK devuelve la primera página y proporciona utilidades de [paginación automática](https://platform.claude.com/docs/es/api/overview#pagination).
```bash cURL
curl https://api.anthropic.com/v1/files \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21"
```
```bash CLI
# Los comandos de listado paginan automáticamente, así que --max-items limita el total
ant files list --max-items 10
```
```python Python
client = anthropic.Anthropic()
files = client.files.list()
print(files)
```
```typescript TypeScript
const client = new Anthropic();
const files = await client.files.list();
console.log(files);
```
```csharp C#
AnthropicClient client = new();
var files = await client.Files.List();
Console.WriteLine(files);
```
```go Go
client := anthropic.NewClient()
files, err := client.Files.List(context.TODO(), anthropic.FileListParams{})
if err != nil {
log.Fatal(err)
}
fmt.Println(files)
```
```java Java
import com.anthropic.models.files.FileListPage;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
FileListPage files = client.files().list();
System.out.println(files);
}
```
```php PHP
$client = new Client();
$files = $client->files->list();
echo $files;
```
```ruby Ruby
client = Anthropic::Client.new
files = client.files.list
puts files
```
Para verificar un conjunto conocido de archivos en una sola solicitud en lugar de paginar, pasa hasta 100 IDs de archivo como parámetros de consulta `ids[]`. Una solicitud con `ids[]` siempre devuelve una sola página (`next_page` es `null`), y cualquier ID que no corresponda a un archivo en tu workspace se omite silenciosamente de `data`; compara los IDs devueltos con los IDs solicitados para detectar los faltantes. `ids[]` no puede combinarse con `page` ni con `limit`.
#### Obtener metadatos de un archivo
Recupera información sobre un archivo específico:
```bash cURL
curl "https://api.anthropic.com/v1/files/$FILE_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21"
```
```bash CLI
ant files retrieve-metadata --file-id "$FILE_ID"
```
```python Python
file = client.files.retrieve_metadata(file_id)
print(file)
```
```typescript TypeScript
const file = await client.files.retrieveMetadata(uploaded.id);
console.log(file);
```
```csharp C#
var file = await client.Files.RetrieveMetadata(fileId);
Console.WriteLine(file);
```
```go Go
metadata, err := client.Files.GetMetadata(context.TODO(), fileID, anthropic.FileGetMetadataParams{})
if err != nil {
log.Fatal(err)
}
fmt.Println(metadata)
```
```java Java
FileMetadata metadata = client.files().retrieveMetadata(fileId);
System.out.println(metadata);
```
```php PHP
$file = $client->files->retrieveMetadata($fileId);
echo $file;
```
```ruby Ruby
file = client.files.retrieve_metadata(file_id)
puts file
```
#### Eliminar un archivo
Elimina un archivo de tu espacio de trabajo:
```bash cURL
curl -X DELETE "https://api.anthropic.com/v1/files/$FILE_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21"
```
```bash CLI
ant files delete --file-id "$FILE_ID"
```
```python Python
client.files.delete(file_id)
```
```typescript TypeScript
await client.files.delete(uploaded.id);
```
```csharp C#
await client.Files.Delete(fileId);
```
```go Go
_, err = client.Files.Delete(context.TODO(), fileID, anthropic.FileDeleteParams{})
if err != nil {
log.Fatal(err)
}
```
```java Java
client.files().delete(fileId);
```
```php PHP
$client->files->delete($fileId);
```
```ruby Ruby
client.files.delete(file_id)
```
### Descargar un archivo
Descarga archivos que fueron creados por [skills](https://platform.claude.com/docs/es/build-with-claude/skills-guide) o la [herramienta de ejecución de código](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool). Los archivos que subes no pueden descargarse. El `file_id` de un archivo generado aparece en el [bloque de contenido `bash_code_execution_tool_result`](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#retrieve-generated-files) de la respuesta de Messages que lo creó:
```bash cURL
curl -X GET "https://api.anthropic.com/v1/files/$FILE_ID/content" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-o downloaded_file.txt
```
```bash CLI
ant files download --file-id "$FILE_ID" --output downloaded_file.txt
```
```python Python
file_content = client.files.download(file_id)
file_content.write_to_file("downloaded_file.txt")
```
```typescript TypeScript
const content = await client.files.download(uploaded.id);
const bytes = Buffer.from(await content.arrayBuffer());
await fsp.writeFile("downloaded_file.txt", bytes);
```
```csharp C#
using var fileContent = await client.Files.Download(fileId);
await using var source = await fileContent.ReadAsStream();
await using var destination = File.Create("downloaded_file.txt");
await source.CopyToAsync(destination);
```
```go Go
func downloadFile(client anthropic.Client, fileID string) error {
resp, err := client.Files.Download(context.TODO(), fileID, anthropic.FileDownloadParams{})
if err != nil {
return err
}
defer resp.Body.Close()
out, err := os.Create("downloaded_file.txt")
if err != nil {
return err
}
defer out.Close()
_, err = io.Copy(out, resp.Body)
return err
}
```
```java Java
try (HttpResponse response = client.files().download(fileId)) {
try (InputStream body = response.body()) {
Files.copy(body, Path.of("downloaded_file.txt"),
StandardCopyOption.REPLACE_EXISTING);
}
}
```
```php PHP
$fileContent = $client->files->download($fileId);
file_put_contents('downloaded_file.txt', $fileContent);
```
```ruby Ruby
file_content = client.files.download(file_id)
File.binwrite("downloaded_file.txt", file_content.read)
```
Un archivo es descargable solo cuando sus metadatos muestran `"downloadable": true`, lo cual ocurre con los archivos creados por skills o la herramienta de ejecución de código. Descargar un archivo que subiste devuelve un error 400.
En la Claude API, los archivos de imagen, video y audio compatibles que Claude produce con la herramienta de ejecución de código, incluidos los archivos creados por skills, llevan Content Credentials C2PA firmadas cuando los descargas. Consulta [Content Credentials en archivos generados](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#content-credentials-on-generated-files) para saber qué contiene la credencial y cómo verificarla.
## Almacenamiento de archivos y límites
### Límites de almacenamiento
* **Tamaño máximo de archivo:** 500 MB por archivo
* **Almacenamiento total:** 1 TB por organización
### Ciclo de vida de los archivos
* Los archivos están limitados al espacio de trabajo en el que se subieron. Cualquier solicitud en el mismo espacio de trabajo puede hacer referencia a ellos; nunca aceptes ID de archivo de fuentes no confiables (consulta la [advertencia sobre el acceso al espacio de trabajo](https://platform.claude.com/docs/es/build-with-claude/files#workspace-scoped-access)).
* Los archivos no se pueden modificar ni renombrar después de subirlos. Para cambiar el contenido de un archivo, sube un archivo nuevo y elimina el anterior.
* Los archivos persisten hasta que los eliminas con el endpoint `DELETE /v1/files/{file_id}` o hasta que alcanzan su `expires_at`.
* Los archivos eliminados no se pueden recuperar.
* Los archivos dejan de ser accesibles a través de la API poco después de su eliminación, pero pueden persistir en llamadas activas a la Messages API y en los usos de herramientas asociados.
* Los archivos que eliminan los usuarios se eliminarán de acuerdo con la [política de retención de datos](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data) de Anthropic.
### Expiración de archivos
Para que un archivo caduque automáticamente, incluye un campo de formulario [`expires_in_seconds`](https://platform.claude.com/docs/es/api/files/upload#upload.expires_in_seconds) al subirlo. El valor es un número entero de segundos entre 3,600 (1 hora) y 7,776,000 (90 días). La marca de tiempo [`expires_at`](https://platform.claude.com/docs/es/api/files#file_metadata.expires_at) resultante (RFC 3339) aparece en cada respuesta de archivo y es `null` para los archivos subidos sin caducidad. La caducidad se establece una sola vez al subir el archivo y no se puede cambiar.
Cuando un archivo alcanza su `expires_at`:
* Descargar su contenido (`GET /v1/files/{file_id}/content`) devuelve un error 404.
* Una solicitud de Messages que hace referencia al archivo falla antes de la inferencia.
* Sus metadatos (`GET /v1/files/{file_id}`) siguen siendo legibles hasta por 30 días, con `expires_at` en el pasado.
* Sigue apareciendo en las respuestas de listado durante ese período; compara `expires_at` con la hora actual para filtrar los archivos expirados.
Eliminar un archivo expirado con `DELETE /v1/files/{file_id}` elimina sus metadatos de inmediato en lugar de esperar a que transcurra el período de 30 días.
La expiración es una función del ciclo de vida, no un control de eliminación garantizada. Después de `expires_at`, el contenido del archivo ya no se puede recuperar a través de la API y se libera de tu cuota de almacenamiento; el contenido subyacente puede conservarse durante un período limitado posterior para revisión de seguridad antes de su eliminación permanente, y los metadatos del archivo siguen visibles hasta por 30 días después de la expiración. Para eliminar un archivo antes de su expiración programada, usa `DELETE /v1/files/{file_id}`.
### Registro de auditoría
Si tu organización tiene habilitada la [Compliance API](https://platform.claude.com/docs/es/manage-claude/compliance-api), su [Activity Feed](https://platform.claude.com/docs/es/manage-claude/compliance-activity-feed) registra las operaciones de la Files API realizadas con una clave de API de Claude o desde la Claude Console: cada subida (`POST /v1/files`), descarga de contenido (`GET /v1/files/{file_id}/content`) y eliminación (`DELETE /v1/files/{file_id}`) aparece como una actividad `platform_file_uploaded`, `platform_file_content_downloaded` o `platform_file_deleted`. Listar archivos y recuperar metadatos de archivos no se registra. Las operaciones que ocurren mientras la Compliance API está desactivada no se registran y no pueden recuperarse después, así que [configura la Compliance API](https://platform.claude.com/docs/es/manage-claude/compliance-api-access) antes de depender de este registro de auditoría. En [Claude Platform on AWS](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws#monitoring-and-logging), audita las operaciones de archivos con eventos de datos de AWS CloudTrail en su lugar.
## Migrar desde `files-api-2025-04-14`
La Files API salió de beta y no necesita ningún encabezado beta. Migrar desde `files-api-2025-04-14` es opcional: las solicitudes que lo envían siguen funcionando y siguen devolviendo las formas de respuesta beta, por lo que una integración existente sigue funcionando hasta que la cambies. Quitar el encabezado cambia esas solicitudes a las formas documentadas en esta página:
| | Con `files-api-2025-04-14` | Sin el encabezado |
| --------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------- |
| Respuesta de listado | `{ data, has_more, first_id, last_id }` | `{ data, next_page }`; pasa `next_page` de vuelta como el parámetro de consulta `page` |
| Cursores de listado | `before_id`, `after_id` | `page`, o hasta 100 `ids[]` (`before_id` y `after_id` devuelven un error 400) |
| `expires_at` en objetos de archivo | No se devuelve | Siempre presente; `null` cuando el archivo no tiene expiración |
| `Content-Type` en la parte del archivo subido | Obligatorio | Opcional; el tipo se detecta cuando se omite |
Para migrar:
1. **Quita el encabezado beta.** Elimina `anthropic-beta: files-api-2025-04-14` de tus solicitudes. Con el SDK, llama a `client.files` (csharp, go: `client.Files`; java: `client.files()`; php: `$client->files`) en lugar de `client.beta.files` (csharp, go: `client.Beta.Files`; java: `client.beta().files()`; php: `$client->beta->files`); mantener `client.beta.files` (csharp, go: `client.Beta.Files`; java: `client.beta().files()`; php: `$client->beta->files`) solo funciona en las [versiones del SDK que ya no envían el encabezado](https://platform.claude.com/docs/es/build-with-claude/files#sdk-beta-namespace). Las versiones anteriores lo envían desde `client.beta.files` (csharp, go: `client.Beta.Files`; java: `client.beta().files()`; php: `$client->beta->files`) incluso cuando no pasas nombres beta.
2. **Actualiza la paginación.** Reemplaza los bucles de `after_id`/`before_id` por el cursor `page`/`next_page`, o usa las utilidades de paginación automática del SDK que se muestran en [Administrar archivos](https://platform.claude.com/docs/es/build-with-claude/files#managing-files).
3. **Lee `expires_at`.** El campo aparece solo sin el encabezado; `null` significa que el archivo no tiene expiración (consulta [Expiración de archivos](https://platform.claude.com/docs/es/build-with-claude/files#file-expiration)).
### Espacio de nombres beta del SDK
A partir de Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, PHP SDK 0.45.0, Ruby SDK 1.67.0 y C# SDK 12.44.0, `client.beta.files` (csharp, go: `client.Beta.Files`; java: `client.beta().files()`; php: `$client->beta->files`) ya no envía `files-api-2025-04-14` y devuelve las mismas estructuras que `client.files` (csharp, go: `client.Files`; java: `client.files()`; php: `$client->files`), con nombres de tipo con el prefijo `Beta` (en PHP, clases en el espacio de nombres `Anthropic\Beta`). Acepta nombres beta mediante `betas` (csharp, go: `Betas`; java: `.addBeta()`) para funciones de Files que están en beta, como el filtrado por `scope_id` bajo un encabezado beta de [Managed Agents](https://platform.claude.com/docs/es/managed-agents/files). Las versiones anteriores del SDK están tipadas con las estructuras beta; si dependes de esos tipos, permanece en una versión anterior hasta que migres.
Las solicitudes que llevan `anthropic-beta: managed-agents-2026-04-01` sin `files-api-2025-04-14` reciben las formas de esta página con una concesión de compatibilidad en `GET /v1/files`: `before_id` y `after_id` todavía se aceptan (no combinables con `page` ni con `ids[]`), y la respuesta de listado incluye `has_more`, `first_id` y `last_id` junto con `next_page`. Las versiones beta posteriores de Managed Agents reciben la forma simple.
## Manejo de errores
Los errores comunes al usar la Files API incluyen:
* **Archivo no encontrado (404):** El `file_id` especificado no existe o no tienes acceso a él.
* **Tipo de archivo no válido (400):** El tipo de archivo no coincide con el tipo de bloque de contenido (por ejemplo, usar un archivo de imagen en un bloque de documento).
* **No descargable (400):** Los archivos que subes tienen `"downloadable": false` y no se pueden descargar. Solo se pueden descargar los archivos creados por skills o la herramienta de ejecución de código.
* **Excede el tamaño de la ventana de contexto (400):** El archivo es más grande que el tamaño de la “context window” (ventana de contexto) (por ejemplo, usar un archivo de texto sin formato de 500 MB en una solicitud a `/v1/messages`).
* **Nombre de archivo no válido (400):** El nombre del archivo no cumple los requisitos de longitud (1–255 caracteres) o contiene caracteres prohibidos (`<`, `>`, `:`, `"`, `|`, `?`, `*`, `\`, `/` o caracteres Unicode 0–31).
* **Archivo demasiado grande (413):** El archivo excede el límite de 500 MB.
* **Límite de almacenamiento excedido (400):** Tu organización alcanzó el límite de almacenamiento de 1 TB.
```json Output
{
"type": "error",
"error": {
"type": "not_found_error",
"message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
},
"request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
}
```
## Uso y facturación
Las operaciones de la Files API son gratuitas:
* Subir archivos
* Descargar archivos
* Listar archivos
* Obtener metadatos de archivos
* Eliminar archivos
El contenido de archivos usado en solicitudes de Messages se cobra como tokens de entrada.
### Límites de velocidad
Las llamadas a la API relacionadas con archivos tienen un “rate limit” (límite de velocidad) de aproximadamente 500 solicitudes por minuto. Para solicitar un límite más alto, [contacta a ventas](mailto:sales@anthropic.com).
## Próximos pasos
Procesa PDFs con Claude. Extrae texto, analiza gráficos y comprende el contenido visual de tus documentos.
Ejecuta código Python y Bash en un contenedor aislado para analizar datos, generar archivos e iterar sobre soluciones.
Procesa y analiza entradas visuales y genera texto y código a partir de imágenes.
## Disponibilidad
Files API está disponible en todos los modelos.
### Compatibilidad con la API
#### [Messages API](https://platform.claude.com/docs/es/build-with-claude/working-with-messages)
* Disponibilidad: Disponible
* Uso: Haz referencia a un archivo subido mediante su `file_id` en un bloque `document`, `image` o `container_upload`.
| Estado | Plataformas en la nube |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Disponible | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry (hosted on Anthropic)](https://platform.claude.com/docs/es/build-with-claude/claude-in-microsoft-foundry) |
#### [Managed Agents](https://platform.claude.com/docs/es/managed-agents/overview)
* Disponibilidad: Disponible
* Uso: Monta archivos subidos en el sandbox de la sesión como recursos de sesión (de solo lectura, en `/mnt/session/uploads`), o haz referencia a un `file_id` en un bloque `image` o `document` de un evento `user.message`. Los archivos que el agente escribe en `/mnt/session/outputs/` se pueden descargar con la Files API.
| Estado | Plataformas en la nube |
| ---------- | --------------------------------- |
| Disponible | Todas las plataformas compatibles |
### Manejo de datos
[Descripción general del manejo de datos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention#feature-eligibility)
| Elemento | Retención de datos cero | HIPAA |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| Estado | No elegible | No elegible |
| Detalles | Los archivos se conservan hasta que se eliminan explícitamente o alcanzan su vencimiento configurado. [Más información](https://platform.claude.com/docs/es/build-with-claude/files#data-retention) | — |
Endpoints aplicables:
* `/v1/files`