GET/resource
resource 论文图片等资源获取
获取论文中的图片等相关资源，用于展示或进一步分析。
概述
通过 file_name 指定正文或解析结果中的图片相对路径，接口返回资源的二进制内容。
不适用场景
- · 不用于搜索图片或发现论文，请先用 agentic-search、meta-search 或 content 找到资源路径。
- · 不用于解释图片内容，上层多模态模型负责理解。
- · 不用于读取正文文本，请使用 content。
能力边界
- · 图片使用相对路径；专利使用 collection=patents、type=file、file_name=doc_id。不要把公开号或完整图片 URL 当作 doc_id。
- · 返回通常是 image/png、image/jpeg、application/pdf 等二进制内容。
- · 资源是否存在取决于目标文献解析结果和账号权限。
- · 调用方应校验 content-type 和响应状态，再展示或处理资源。
鉴权
统一使用 API Key Bearer Token 鉴权，详见统一鉴权章节。在 HTTP Header 中加入：
Authorization: Bearer YOUR_API_TOKEN
请求示例
curl
curl -G https://api.sciverse.space/resource \
-H "Authorization: Bearer YOUR_API_TOKEN" \
--data-urlencode "file_name=papers/2025/abcd/fig1.png" \
-o fig1.png专利源文件
BASE_URL="${BASE_URL:-https://api.sciverse.space}"
: "${SCIVERSE_API_TOKEN:?Set SCIVERSE_API_TOKEN}"
DOC_ID="YOUR_DOC_ID_FROM_META_SEARCH"
curl --fail -sS -G "${BASE_URL}/resource" \
-H "Authorization: Bearer ${SCIVERSE_API_TOKEN}" \
--data-urlencode 'collection=patents' \
--data-urlencode 'type=file' \
--data-urlencode "file_name=${DOC_ID}" \
-o patent-source.zip请求参数（URL query）
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| collection | string | 可选 | 专利必须传 patents；省略时按论文处理。 默认 papers范围 papers / patents |
| file_name | string | 必填 | 图片：安全的相对路径；专利源文件：检索返回的 doc_id（SHA-256）。 |
| type | string | 可选 | 图片用 image；专利源文件必须用 file。 默认 image范围 image / file |
响应结构
响应为二进制流；常见 Content-Type：image/jpeg、image/png、application/pdf 等。
| 字段 | 类型 | 说明 |
|---|---|---|
| Content-Type | header | 附件的 MIME 类型。 |
| Content-Disposition | header | 资源文件名与展示方式。 |
| X-Request-ID | header | 请求追踪 ID。 |
| body | binary | 附件原始二进制内容。 |
错误码
| 错误码 | 信息 | 说明 |
|---|---|---|
| 400 | INVALID_REQUEST | file_name 缺失或路径非法。 |
| 401 | UNAUTHORIZED | 鉴权失败。 |
| 404 | NOT_FOUND | 资源不存在。 |
| 429 | RATE_LIMITED | 触发账号配额限制。 |
| 500/502/503 | UPSTREAM_UNAVAILABLE | 服务异常。 |
| 403 | FORBIDDEN | 获取专利源文件需要 internal 角色。 |
通用错误码请参考「错误码」章节。
参数边界
| 限制项 | 值 |
|---|---|
| 专利源文件 | 仅 internal 角色；原文件可能含多篇专利。不承诺断点续传。 |
重试建议
- · 建议重试：500 / 502 / 503
- · 不应重试：400 / 401
FAQ
file_name 从哪里获取？
图片路径来自正文或解析结果；专利源文件直接使用 meta-search 返回的 doc_id。
可以传完整图片 URL 吗？
图片应使用相对路径。专利源文件应使用 doc_id，并传 collection=patents 和 type=file。
resource 会解释 Figure 或 Table 吗？
不会。它只返回二进制资源；图表理解需要上层多模态模型或业务逻辑。
资源获取失败怎么处理？
检查 file_name 是否来自 Sciverse 返回、路径是否安全、账号是否有权限，并根据 404/403/429 做降级或重试。
说明
- · 示例默认使用生产地址；验证预览环境时先设置 BASE_URL，并将该环境的 token 放入 SCIVERSE_API_TOKEN。查询、全文读取、源文件下载分别校验权限；下载专利源文件需要 internal 角色，返回的可能是包含多篇专利的原始 ZIP。
还没有 API Key？
登录控制台「密钥」即可创建。同一套 API Key 可用于已开通的 Sciverse、点石与 Skills 能力，提供基础试用额度，具体以账号权限为准。