# 地址与接口

> 配置 APIMart 客户端，使用平台虚拟密钥查询模型、提交生成并读取结果。

Base URL：`https://platform.sgt.site/apimart/v1`

本栏目说明 APIMart 兼容协议。它使用 APIMart 的模型名称、请求字段和任务响应；支持范围以本栏目为准。调用使用平台模型授权和企业人民币预算，不使用 APIMart 官方账号的凭据或余额。

<a id="apimart-access-h-8d2dfac3"></a>

## 配置地址和虚拟密钥

在允许自定义服务地址的 APIMart SDK 或客户端中填写：

| 配置项 | 填写内容 | 说明 |
| --- | --- | --- |
| Base URL | `https://platform.sgt.site/apimart/v1` | 已包含版本前缀；不要重复追加 `/apimart/v1` |
| API Key / 密钥 | 你的平台虚拟密钥 | 使用平台签发给使用人或应用的虚拟密钥，示例中的 `YOUR_VIRTUAL_KEY` 需替换为完整值 |

每次查询和生成都在 HTTP 请求头中传入：

```http
Authorization: Bearer YOUR_VIRTUAL_KEY
```

`Bearer` 后保留一个空格。POST JSON 请求还需 `Content-Type: application/json`。签名下载地址自带限时读取授权，无需 `Authorization` 请求头。

虚拟密钥须有效，所属使用人或应用须具备消费身份及目标模型授权。图片、视频生成还要求主体已使用企业人民币预算。平台管理权限不授予模型消费资格；如果虚拟密钥设置了 IP、模型或额度限制，也会照常校验。

<a id="apimart-access-h-42acbcd4"></a>

## 第一次请求：查询可用图片模型

先用只读目录请求确认地址和鉴权配置，再从响应的 `data[].id` 选择生成请求的 `model`。此请求不调用模型服务，不产生模型生成费用。

```bash
curl --request GET "https://platform.sgt.site/apimart/v1/models?category=image" \
  --header "Authorization: Bearer YOUR_VIRTUAL_KEY"
```

成功返回 HTTP 200，正文为 `{"success":true,"object":"list","data":[...]}`。每个条目代表当前密钥可见的一个 APIMart 模型，`data: []` 表示没有符合条件的模型。完整参数、响应示例和排查方式见[获取模型列表与名称映射](apimart-models.md)。

后续按需进入[图片生成](apimart-images.md)或[视频生成](apimart-videos.md)，保存提交返回的 `task_id`，再通过[任务查询](apimart-tasks.md)获取状态与结果。

<a id="apimart-access-h-b2855811"></a>

## 接口一览

下表路径相对于本页 Base URL。例如 `/models` 的完整地址是 `https://platform.sgt.site/apimart/v1/models`。

| 方法 | 相对路径 | 接口名称与用途 | 主要返回内容 |
| --- | --- | --- | --- |
| GET | `/models` | [获取可用模型列表](apimart-models.md)；可按 `image`、`video`、`chat` 筛选 | 模型数组，含公共 `id` 和 `category` |
| POST | `/images/generations` | [创建图片生成任务](apimart-images.md)；按模型支持的提示词、参考图和尺寸提交 | 已提交的 `task_id`，不是最终图片 |
| POST | `/videos/generations` | [创建视频生成任务](apimart-videos.md)；按模型支持的文本或参考媒体提交 | 已提交的 `task_id`，不是最终视频 |
| POST | `/chat/completions` | 调用 `category=chat` 的文本模型；沿用 Chat Completions 请求及流式约定 | 非流式文本响应或 SSE 增量，不创建媒体任务 |
| GET | `/tasks/{task_id}` | [查询任务状态与结果](apimart-tasks.md) | 生成状态、产物及结算信息 |
| GET | `/images/tasks/{task_id}` | 图片客户端使用的查询兼容别名 | 与 `/tasks/{task_id}` 相同的响应 |
| GET / HEAD | `/tasks/{task_id}/artifacts/{index}?expires=…&sig=…` | [签名产物下载](apimart-content.md)；使用任务查询返回的完整链接，无需再附虚拟密钥 | 文件正文或响应头，支持 Range |
| GET | `/tasks/{task_id}/content/{index}` | [鉴权产物下载](apimart-content.md)；保留给已有客户端，需虚拟密钥 | 指定产物文件，支持 Range |

<a id="apimart-access-h-ba85f423"></a>

## 提交、查询与下载约定

图片、视频提交为 JSON，正文最多 4 MiB；数值、布尔值必须使用 JSON 对应类型。显式 `null`、不支持的字段及冲突别名均返回 400。客户端能填写某个 APIMart 参数，不代表平台已支持；提交前请对照相应生成页的字段白名单。

查询和鉴权下载校验任务所属主体、企业以及当前虚拟密钥的模型/渠道权限。同一企业中的其他使用人或应用不能直接读取当前主体的任务；权限撤销后，查询和鉴权下载同样受校验拦截，不再签发新的签名下载地址。

任务查询返回的图片、视频 `url` 是上游产物链接或签名下载地址，读取这些链接时不附带任何密钥。已发出的链接在有效期内仍可读取，平台无法单独收回。完整的有效期、下载和归档区别见[产物下载](apimart-content.md)。

`/tasks/{task_id}` 及其下载只读取通过 `/apimart/v1` 提交的任务。其他协议创建的任务在这里返回 404，应使用创建任务时对应的查询入口。

请求失败时请读取 HTTP 状态、`error.type`、`error.message` 和 `request_id`，详见[HTTP 错误](apimart-errors.md)。如果提交响应带有 `task_id` 或 `reconciliation_required: true`，先保存标识并查询原任务；结果待核对时不要重新提交生成请求。