ia

Internet Archive CLI 技能

此技能可通过 internetarchive Python 包中的 ia 命令行工具与 Internet Archive（archive.org）交互。

条目

条目是 archive.org 上的基本单位，是共享通用元数据的相关文件的逻辑集合。条目可以是书籍、歌曲、专辑、数据集、电影、图像或图像集等。每个条目在整个档案中都有唯一标识符。

每个条目都包含：

• 原始上传文件
• 衍生文件（由 archive.org 自动生成）
• <identifier>_meta.xml - 条目级元数据
• <identifier>_files.xml - 文件级元数据

条目必须属于某个合集。

条目限制

约束	建议值	硬性限制
条目总大小	小于 100GB	~1TB
每个条目的文件数	小于 10,000	250,000（超过 10,000 个时性能会下降）
单个文件大小	小于 50GB	500-700GB
每日上传量	小于 1,000 个文件	5,000 个文件（zip 文件按 1 个计）

永久 URL 模式：

• 详情页：https://archive.org/details/<identifier>
• 下载目录：https://archive.org/download/<identifier>
• 特定文件：https://archive.org/download/<identifier>/<filename>
• 条目历史记录：https://archive.org/history/<identifier>

**警告：**切勿链接到 ia802304.us.archive.org 这类特定服务器的 URL——条目在服务器之间迁移时，这些链接会失效。请始终使用上述规范的 archive.org URL。

更多详情，请参阅：https://archive.org/developers/items.html

衍生文件

将文件上传到 Internet Archive 时，系统会自动生成衍生文件，即转换为不同格式和分辨率的版本。例如：

• 视频：转码为 h.264、Ogg 和各种比特率
• 音频：转换为 MP3（多种比特率）、Ogg Vorbis、FLAC
• 文本/书籍：OCR 处理、可搜索 PDF、EPUB、DjVu
• 图像：缩略图、JPEG 2000、不同分辨率的版本

衍生文件让内容能够在不同设备和带宽条件下访问。你可以在 ia list 输出中识别衍生文件——它们有一个指向源文件的 original 字段。

若要在上传期间跳过衍生文件生成，请使用 --no-derive：

ia upload my-item file.mp4 --metadata="mediatype:movies" --no-derive

完整的源格式及其生成的衍生文件列表，请参阅：https://archive.org/help/derivatives.php

元数据架构

Internet Archive 条目使用基于 XML 的元数据。要点如下：

• 必填字段：identifier、mediatype
• 建议字段：title、description、creator、date、subject、collection、language
• **可重复字段：**合集、创作者、主题和语言支持多个值
• **自定义字段：**你可以定义任意数量的自定义元数据字段（必须遵循 XML 命名规则）

标识符要求：

• 只能包含 ASCII 字母数字字符、下划线、连字符或句点
• 必须以字母数字字符开头
• 长度为 5-100 个字符（建议为 5-80 个字符）
• 设置后必须唯一且不可更改

完整的元数据架构参考，请参阅：https://archive.org/developers/metadata-schema

合集

合集将相关条目归在一起。要点如下：

• 只有 IA 工作人员可以创建合集——用户必须申请创建
• 新合集至少需要 50 个条目
• 条目必须彼此相关，通常属于相同媒体类型
• 申请后，合集创建最多需要两周

如需申请创建合集，请联系 Internet Archive，并提供：

• 用于标识条目的条目标识符列表或搜索查询
• 期望的合集标识符（5-80 个字符，仅限字母数字字符）
• 合集标题和描述
• 至少一个主题标签

公开上传合集（任何人都可以上传到其中）：

• opensource_movies、opensource_audio、opensource_media - 通用媒体
• community_texts、community_video、community_audio - 社区贡献

其他合集仅允许指定的上传者上传。

工具检测与安装

在使用任何 ia 命令之前，请先检查是否已安装该工具：

ia --version

如果找不到 ia 命令，请使用 uv 安装：

uv tool install internetarchive

其他安装方式：

• pipx install internetarchive
• pip install internetarchive

安装后，使用 ia --version 验证是否可用。

全局选项

以下选项适用于所有 ia 命令：

Option	Description
-h, --help	显示帮助信息
-v, --version	显示版本
-c FILE, --config-file	配置文件路径
-l, --log	启用日志记录
-d, --debug	启用调试输出

配置与身份验证

检查 ia 是否已配置：

ia configure --whoami

如果尚未配置（显示错误或内容为空），用户需要设置凭据：

1. 交互式设置：运行 ia configure 并按提示操作
2. 获取凭据：从 https://archive.org/account/s3.php 获取 IA-S3 密钥
3. 配置位置：保存至 ~/.config/ia.ini

配置选项

Option	Description
--whoami	打印当前已通过身份验证的用户
--show	将当前配置以 JSON 格式打印
--check	验证 IA-S3 密钥（有效时退出码为 0，否则为 1）

# Show current config
ia configure --show

# Validate keys (useful in scripts)
ia configure --check && echo "Keys valid"

环境变量

可替代配置文件使用：

export IA_ACCESS_KEY_ID="your-access-key"
export IA_SECRET_ACCESS_KEY="your-secret-key"

注意：上传和修改元数据需要配置。无需身份验证即可搜索和下载公开内容。

用户代理标识（必需）

**所有发往 Internet Archive 的请求都必须包含恰当的 User-Agent 字符串，以明确标识请求来源。**这适用于通过任何工具发出的每个请求，包括 ia CLI、Python 库、直接 API 调用、curl 或任何其他 HTTP 客户端。这对于 AI Agent、机器人和自动化工具至关重要。

ia CLI 会自动在默认 User-Agent 中包含访问密钥：

internetarchive/5.7.2 (Linux x86_64; N; en; ACCESS_KEY) Python/3.11.0

使用 Claude Code 或其他 AI/LLM Agent 时，必须附加自定义后缀，其中包含：

• 工具或 Agent 的名称和版本（例如，“Claude Code/1.0.0”）
• 使用的模型（如适用，例如“claude-sonnet-4-20250514”）
• 与自动化相关的其他上下文信息

--user-agent-suffix CLI 选项和 user_agent_suffix 配置项要求 internetarchive 版本为 5.7.2 或更高。默认 User-Agent（包括访问密钥）始终会发送，后缀会附加在其后。

CLI：

ia --user-agent-suffix "Claude Code/1.0.0 (claude-sonnet-4-20250514)" download my-item

INI 文件（~/.config/internetarchive/ia.ini）：

[general]
user_agent_suffix = Claude Code/1.0.0 (claude-sonnet-4-20250514)

Python API：

from internetarchive import get_session

session = get_session(config={
    'general': {'user_agent_suffix': 'Claude Code/1.0.0 (claude-sonnet-4-20250514)'}
})

最终生成的 User-Agent 类似于：

internetarchive/5.7.2 (Linux x86_64; N; en; ACCESS_KEY) Python/3.11.0 Claude Code/1.0.0 (claude-sonnet-4-20250514)

这有助于 Internet Archive 跟踪使用模式、排查问题并维护服务质量。请始终提供具体信息，包括版本号、模型标识符，以及足以将你的工具与其他工具区分开的详细信息。

搜索操作

搜索 Internet Archive 目录：

ia search '<query>'

搜索参数

Parameter	Description
--itemlist	仅输出标识符，每行一个
-n, --num-found	仅打印结果数量
-s, --sort	对结果排序：--sort='field desc' 或 --sort='field asc'
-f, --field	返回指定的元数据字段（可重复使用）
-F, --fts	全文搜索（搜索文本内容，而不仅是元数据）
--parameters	原始查询参数：--parameters="page=N&rows=N"

# Get result count only
ia search 'collection:nasa' -n

# Sort by date descending
ia search 'mediatype:texts' --sort='date desc'

# Return specific fields
ia search 'collection:nasa' --field=identifier --field=title

排序字段

--sort 可使用的常见排序字段：

字段	描述
date	内容日期
publicdate	项目发布到 archive.org 的时间
addeddate	添加到存档的时间
updatedate	最后更新时间
title / titleSorter	按标题字母顺序排序
creator / creatorSorter	按创作者字母顺序排序
downloads	总下载量
week	本周下载量
month	本月下载量
num_reviews	评论数
num_favorites	收藏数
item_size	项目总大小
files_count	文件数

使用 asc 或 desc 后缀：

ia search 'mediatype:audio' --sort='downloads desc'
ia search 'collection:books' --sort='publicdate asc'
ia search 'creator:NASA' --sort='title asc'

搜索查询语法

Internet Archive 使用 Apache Lucene 查询语法。默认运算符为 AND（必须包含所有词）。

查询运算符

运算符	描述
AND	必须包含所有词（默认）
OR	可以包含其中任意词
NOT	排除包含指定词的文档（至少需要一个正向词）
( )	将子句分组以构成子查询

按字段搜索

使用 field:value 语法搜索特定元数据字段：

查询	描述
'title:"search text"'	按标题搜索
'creator:"Author Name"'	按创作者／作者搜索
'subject:"topic"'	按主题搜索
'description:"text"'	按描述搜索
'collection:name'	搜索某个合集中的项目
'mediatype:texts'	按媒体类型搜索（texts、movies、audio、software、image、data）
'contributor:smithsonian'	按贡献者搜索
'language:eng'	按语言代码搜索
'format:pdf'	搜索包含特定文件格式的项目
'isbn:9780123456789'	按 ISBN 搜索
'licenseurl:http*by-nc*'	按 Creative Commons 许可搜索

范围查询

使用方括号或圆括号搜索上下限之间的值：

语法	描述
[1000 TO 2000]	闭区间（包含上下限）
{1000 TO 2000}	开区间（不包含上下限）
[1000 TO null]	开放范围（1000 或更大）
[null TO 2000]	开放范围（2000 或更小）

日期字段

可搜索的日期字段：addeddate、createdate、date、indexdate、publicdate、reviewdate、updatedate、oai_updatedate

查询	描述
'date:[2020-01-01 TO 2024-12-31]'	日期范围
'publicdate:[2024-01-01 TO 2024-06-30]'	按发布日期搜索
'indexdate:[2024-01-01T00:00:00Z TO 2024-12-31T23:59:59Z]'	使用时间戳
'date:2024*'	使用通配符搜索年份（非范围）

模糊查询

添加 ~ 以匹配拼写近似的词：

ia search 'title:buttonwood~'

# Boost fuzzy matches with weights
ia search '(title:buttonwood~)^150 OR (subject:buttonwood~)^100'

搜索缺失字段

查找不存在某个字段的项目：

ia search 'collection:microfiche AND NOT _exists_:creator'

按上传者搜索

按上传者的用户项目、屏幕名称或电子邮件搜索：

ia search '_uploader_useritem:@username'
ia search '_uploader_screenname:"Display Name"'
ia search 'uploader:[email protected]'

其他可搜索字段

除标准元数据外，还可以按以下字段搜索：

• downloads - 下载次数
• item_size - 项目总大小（字节）
• files_count - 文件数
• collection_size - 合集大小
• item_count - 合集中的项目数

ia search 'collection:opensource AND downloads:[1000 TO null]'
ia search 'mediatype:movies AND item_size:[1000000000 TO null]'

组合查询

# AND is implicit between terms
ia search 'collection:nasa mediatype:image'

# Explicit operators
ia search 'collection:nasa AND mediatype:image'
ia search 'mediatype:texts OR mediatype:audio'
ia search 'collection:opensource NOT mediatype:software'

# Grouped subqueries
ia search '(mediatype:texts OR mediatype:audio) AND creator:"Mark Twain"'

全文搜索

使用 -F（或 --fts）标志搜索项目的实际文本内容，而不仅仅是元数据。这对于搜索书籍、文档和 OCR 处理材料等文本合集尤其有效。

全文搜索基础用法：

ia search -F 'collection:collection_name "search phrase"'

工作原理：

• 搜索文档的全文内容（经过 OCR 处理的 PDF、文本文件等）
• 查找特定引文或段落时，比仅搜索元数据更有效
• 项目必须包含可搜索文本（OCR 文本或文本文件）
• 可与合集和元数据筛选条件组合使用

全文搜索语法：

• 使用引号搜索精确短语："complete phrase"
• 与元数据筛选条件组合：collection:name AND "text to find"
• 对经过 OCR 处理的文本合集效果最佳

示例

# Search NASA images
ia search 'collection:nasa mediatype:image' --parameters="rows=10"

# Search public domain books
ia search 'subject:"public domain" mediatype:texts'

# Get just identifiers
ia search 'creator:"Mark Twain"' --itemlist

# Full-text search within a text collection
ia search -F 'collection:books "climate change"'

# Full-text search for a specific quote in public domain texts
ia search -F '"to be or not to be" mediatype:texts'

# Full-text search with collection filter and pagination
ia search -F 'collection:usgovernmentdocuments "artificial intelligence"' --parameters="rows=20"

下载操作

从 Internet Archive 条目下载文件：

ia download <identifier>

下载参数

参数	描述
--glob="*.ext"	仅下载匹配的文件（使用 | 匹配多个文件：'*.mp4|*.webm'）
--exclude="*pattern*"	排除与模式匹配的文件
--format="FORMAT"	下载指定的衍生格式
--source=SOURCE	按来源筛选：original、derivative、metadata
--exclude-source=SOURCE	按来源类型排除文件
--destdir=path	下载到指定目录
--no-directories	展平目录结构
-s, --stdout	将文件写入标准输出（用于管道操作）
--dry-run	显示将要下载的内容
--checksum	跳过已存在且校验和正确的文件
--on-the-fly	下载即时生成的文件（生成的衍生文件）
--search="QUERY"	从搜索结果中下载
--itemlist=FILE	下载文件中列出的条目

按来源类型筛选

使用 --source 和 --exclude-source 按文件来源筛选：

# Download only original files (skip all derivatives)
ia download my-item --source=original

# Download originals and metadata, skip derivatives
ia download my-item --exclude-source=derivative

# Download only metadata files
ia download my-item --source=metadata

示例

# Download all files from an item
ia download TripDown1905

# Download specific files by name
ia download TripDown1905 file1.mp4 file2.ogv

# Download only MP4 files
ia download TripDown1905 --glob="*.mp4"

# Download MP4s but exclude low-quality versions
ia download TripDown1905 --glob="*.mp4" --exclude="*512kb*"

# Download specific format
ia download TripDown1905 --format='512Kb MPEG4'

# Download to specific directory
ia download TripDown1905 --destdir=./downloads

# Download from search results
ia download --search 'collection:opensource_movies' --glob="*.mp4"

# Download items from a list file
ia search 'collection:glasgowschoolofart' --itemlist > itemlist.txt
ia download --itemlist itemlist.txt

# Preview what will be downloaded
ia download my_item --dry-run

上传操作

将文件上传到 Internet Archive（需要身份验证）：

ia upload <identifier> file1 file2 --metadata="mediatype:value"

必需的元数据

必须提供 mediatype 字段。常见值：

• texts - 书籍、文档、PDF
• movies - 视频文件
• audio - 音乐、播客、声音
• software - 程序、游戏
• image - 照片、图形
• data - 数据集、档案

上传参数

参数	描述
--metadata="key:value"	设置元数据（可重复使用）
--header="key:value"	设置 HTTP 标头
--checksum	跳过已上传的文件
-v, --verify	验证上传后数据未损坏
--no-derive	跳过衍生文件处理
--retries=N	重试次数
--remote-name=NAME	设置远程文件名（用于标准输入上传）
--keep-directories	在远程文件名中保留目录结构
-o, --open-after-upload	上传后在浏览器中打开条目
--file-metadata=FILE	从 JSONL 文件读取文件级元数据
--spreadsheet=FILE	从 CSV 电子表格批量上传

常见元数据字段

--metadata="title:My Document Title"
--metadata="creator:Author Name"
--metadata="description:A description of the content"
--metadata="subject:topic1;topic2"
--metadata="collection:community_texts"
--metadata="date:2024-01-15"
--metadata="language:eng"

示例

# Upload a PDF document
ia upload my-document-2024 document.pdf \
  --metadata="mediatype:texts" \
  --metadata="title:My Document" \
  --metadata="creator:John Doe"

# Upload multiple files
ia upload my-archive file1.pdf file2.pdf file3.pdf \
  --metadata="mediatype:texts" \
  --metadata="title:Document Collection"

# Upload with checksum verification and retries
ia upload my-item large-file.zip \
  --metadata="mediatype:data" \
  --checksum \
  --retries=10

# Upload from stdin
cat data.gz | ia upload my-item - \
  --remote-name=data.gz \
  --metadata="mediatype:data"

# Bulk upload using spreadsheet
ia upload --spreadsheet=metadata.csv

注意：

• 如果未指定，条目的默认 mediatype 为 data
• 只有在上传后获得管理员支持，才能更改媒体类型
• 衍生文件的生成耗时从数秒到数天不等，具体取决于文件类型和系统负载
• 条目通常会在几分钟内出现在搜索结果中，但最长可能需要 24 小时

测试集合

上传到 test_collection 进行验证——条目会在约 30 天后自动移除：

ia upload my-test-item file.pdf \
  --metadata="mediatype:texts" \
  --metadata="collection:test_collection"

标识符指南

• 使用小写字母、数字和连字符
• 不要使用空格或特殊字符
• 名称应具有描述性且简洁
• 检查标识符是否存在：ia metadata <identifier> --exists

条目缩略图

要为条目设置自定义缩略图，请上传名为 <identifier>_itemimage.jpg 的图像：

ia upload my-item my-item_itemimage.jpg

限制下载

若要让文件可供流式播放但不可下载，请将条目添加到 stream_only 集合：

ia metadata <identifier> --append-list="collection:stream_only"

元数据操作

查看和修改条目元数据：

# View metadata (JSON output)
ia metadata <identifier>

# Extract specific field with jq
ia metadata <identifier> | jq '.metadata.date'

# List file formats contained in an item
ia metadata <identifier> --formats

# Modify metadata (set or replace)
ia metadata <identifier> --modify="title:New Title"
ia metadata <identifier> --modify="foo:bar" --modify="baz:value"

# Remove a metadata field
ia metadata <identifier> --modify="fieldname:REMOVE_TAG"

# Append value to existing field
ia metadata <identifier> --append="title:Subtitle Here"

# Append to list field (e.g., subjects)
ia metadata <identifier> --append-list="subject:new topic"

# Remove specific value from list field
ia metadata <identifier> --remove="subject:old topic"

# Modify file-level metadata
ia metadata <identifier> --target="files/foo.txt" --modify="title:My File"

# Bulk updates from spreadsheet
ia metadata --spreadsheet=metadata.csv

列表操作

列出 Internet Archive 条目中的文件：

ia list <identifier>

显示所有文件的详细信息（名称、大小、格式）。

列表参数

参数	描述
--columns=name,size	指定要显示的列
--glob="*.pdf"	按模式筛选
-l, --location	输出每个文件的完整 URL
-a, --all	列出所有可用的文件信息
-v, --verbose	输出列标题

# List with full URLs
ia list my-item --location

# List all file info with headers
ia list my-item --all --verbose

# List specific columns
ia list my-item --columns=name,size,format

任务和作业

查看目录任务（上传、衍生等）的状态：

# Check tasks for a specific item
ia tasks <identifier>

# Check all your tasks
ia tasks

隐藏和取消隐藏条目

要隐藏条目（禁止公开访问）或取消隐藏：

# Dark an item (requires comment)
ia tasks <identifier> --cmd=make_dark.php --comment="Reason for darking"

# Undark an item
ia tasks <identifier> --cmd=make_undark.php --comment="Reason for undarking"

使用 GNU Parallel 执行批量操作

批量处理大量项目时，可使用 GNU Parallel 并发运行 ia 命令。

安装

# macOS
brew install parallel

# Debian/Ubuntu
apt install parallel

基本用法

将项目标识符通过管道传递给 parallel，并使用 {} 作为占位符：

# Fetch metadata for many items
cat itemlist.txt | parallel 'ia metadata {}'

# Download multiple items
cat itemlist.txt | parallel 'ia download {}'

谨慎执行批量处理

为确保批量操作可靠，请使用作业日志跟踪进度并处理失败：

# Step 1: Create item list
ia search 'collection:myproject' --itemlist > itemlist.txt

# Step 2: Run with job logging
cat itemlist.txt | parallel --joblog job.log 'ia download {}'

# Step 3: Check for failures
echo $?  # 0 = all succeeded

# Step 4: Retry only failed jobs
parallel --retry-failed --joblog job.log

作业日志的优势

--joblog 文件会记录每条命令的退出状态，因此你可以：

• 恢复中断的批处理作业
• 仅重试失败的项目，而无需重新处理成功的项目
• 审查成功和失败的操作

先进行试运行

批量执行前，务必先预览：

cat itemlist.txt | parallel --dry-run 'ia download {}'

速率限制

控制并发数，避免给服务造成过大负担：

# Limit to 4 concurrent jobs
cat itemlist.txt | parallel -j4 'ia download {}'

# Add delay between jobs
cat itemlist.txt | parallel --delay 1 'ia download {}'

参见：https://archive.org/developers/internetarchive/parallel.html

最佳实践

1. 上传前务必先配置——先运行 ia configure
2. 使用有意义的标识符——清晰、全小写，并以连字符分隔
3. 填写适当的元数据——至少包含 mediatype、title、creator
4. 上传前先检查——确认标识符不存在：ia metadata <id>
5. 使用校验和——大型上传时添加 --checksum，以支持续传
6. 遵守速率限制——不要频繁发送请求；批量操作时添加延迟
7. 先进行试运行——使用 --dry-run 预览操作
8. 先使用 test_collection——在提交到永久集合前验证上传内容
9. 将大型文件集合打包为 Zip——上传前将许多小文件打包成归档文件
10. 指定语言——设置 language 元数据，以便对文本进行正确的 OCR 处理

错误处理

错误	解决方案
"not configured"	运行 ia configure 或设置环境变量
"identifier exists"	选择其他标识符
"permission denied"	检查 https://archive.org/account/s3.php 中的凭据
"network error"	重试操作；检查互联网连接
"item not found"	确认标识符拼写正确
"429 Too Many Requests"	受到速率限制；等待后使用 Retry-After 标头中的值重试
项目未显示在搜索结果中	通常会在几分钟内显示；使用 ia tasks <identifier> 检查待处理作业
派生任务失败	检查文件名字符、文件格式和语言元数据

快速参考

# Search
ia search 'query'
ia search 'query' --itemlist

# Download
ia download <identifier>
ia download <identifier> --glob="*.pdf"

# Upload (requires auth)
ia upload <identifier> files --metadata="mediatype:texts"

# Metadata
ia metadata <identifier>
ia metadata <identifier> --modify="title:New Title"

# List files
ia list <identifier>

# Tasks
ia tasks <identifier>

# Config
ia configure
ia configure --whoami

# Install
uv tool install internetarchive

API 参考

如需 CLI 之外的编程访问方式，请参阅完整的开发者文档：https://archive.org/developers

核心 API

API	说明
Items	了解项目结构和访问方式
Metadata Schema	完整的元数据字段参考
Metadata Read	通过 API 获取项目元数据
Metadata Write	通过 API 修改项目元数据
IAS3	用于上传的 S3 兼容 API
Tasks	任务队列管理

其他 API

API	说明
Changes	跟踪整个档案中的项目变更
Views	查看量和下载量统计的访问方式
Reviews	管理项目评论
Simple Lists	创建项目关系和列表
OCR Service	文本识别服务
PDF Service	PDF 生成和处理

Python 库

如需集成 Python，请参阅：internetarchive library

TypeScript 库（第三方）

社区维护的 TypeScript 移植版本：internetarchive-ts（文档）

注意：此项目仍在开发中，并非由 Internet Archive 官方维护。