# DataJion 使用指南

本文档面向 DataJion 平台客户，覆盖公开模型调用、平台文件与生成资产、火山方舟素材库、异步任务和费用查询接口。

## 基础信息

- Base URL：`https://datajion.caihdata.com`
- 大多数接口使用 `Authorization: Bearer <YOUR_API_KEY>` 鉴权。
- Anthropic Messages 使用 `x-api-key: <YOUR_API_KEY>` 和 `anthropic-version: 2023-06-01`。
- 平台统一 Asset Store 与火山方舟素材库是两套不同资源体系：`file_id`、`generated-assets` 不等同于火山 `AssetId`、`GroupId`。
- Claude Code Skill 下载：`/downloads/datajion-api-skill.zip`

## 快速开始

使用平台 API Key 访问公开模型、平台文件、火山素材库和费用查询接口。

## 下载 Claude Code Skill

`GET /downloads/datajion-api-skill.zip`

协议：Skill

下载给客户 Claude Code 安装的 DataJion API Skill。该包只包含公开模型调用、资产调用和费用查询说明，不包含任何密钥。

鉴权：
- `无需鉴权`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `download path` | path:string | 是 | 固定下载路径 /downloads/datajion-api-skill.zip。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `datajion-api/SKILL.md` | zip entry | 是 | Skill 入口文件，定义触发条件和客户侧调用流程。 |
| `datajion-api/references/api.md` | zip entry | 是 | 完整 API 参考、curl 示例和注意事项。 |

### 请求样例

```bash
curl -O "https://datajion.caihdata.com/downloads/datajion-api-skill.zip"
```

### 响应样例

```text
datajion-api/
  SKILL.md
  references/api.md
```

### 注意事项

- 下载后解压到客户自己的 Claude Code Skill 目录，API Key 仍由客户本地配置。

## 列出可用模型

`GET /v1/models`

协议：OpenAI 兼容

查询当前 API Key 可调用的模型列表。返回结果与 OpenAI Models 列表结构兼容，可用于客户端启动时做模型发现。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `request body` | none | 否 | 该接口不需要请求体。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `object` | string | 是 | 固定为 list。 |
| `data[].id` | string | 是 | 可传入调用接口的模型编码。 |
| `data[].object` | string | 是 | 固定为 model。 |
| `data[].owned_by` | string | 否 | 模型厂商或平台展示归属。 |

### 请求样例

```bash
curl "https://datajion.caihdata.com/v1/models" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

### 响应样例

```json
{
  "object": "list",
  "data": [
    {"id": "gpt-5.5", "object": "model", "owned_by": "datajion"}
  ]
}
```

### 注意事项

- 返回内容会按当前 API Key 的租户、应用和模型开通范围过滤。

## OpenAI 兼容

适用于 OpenAI SDK 或 OpenAI 兼容客户端的文本、图片、视频、文件接口。

## Chat Completions

`POST /v1/chat/completions`

协议：OpenAI 兼容

发送多轮对话消息并返回模型回复。适合继续使用 OpenAI SDK 的 chat.completions 调用形态。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `model` | body:string | 是 | 模型编码，例如 gpt-5.5。 |
| `messages` | body:array | 是 | 对话消息数组，元素包含 role 和 content。 |
| `stream` | body:boolean | 否 | 是否使用 SSE 流式返回。 |
| `temperature` | body:number | 否 | 采样温度，是否生效取决于上游模型。 |
| `max_tokens` | body:number | 否 | 最大输出 token 数。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `id` | string | 是 | 请求返回 ID。 |
| `choices[].message.content` | string | 是 | 模型回复文本。 |
| `choices[].finish_reason` | string | 否 | 结束原因，例如 stop 或 length。 |
| `usage` | object | 否 | 输入、输出和总 token 用量。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/v1/chat/completions" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"你好"}]}'
```

### 响应样例

```json
{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "你好，我可以帮你接入 DataJion API。"}, "finish_reason": "stop"}],
  "usage": {"prompt_tokens": 12, "completion_tokens": 18, "total_tokens": 30}
}
```

### 注意事项

- 流式调用时响应为 text/event-stream；计费以最终记录的 usage 或协议事实为准。

## Responses

`POST /v1/responses`

协议：OpenAI 兼容

使用 Responses API 进行文本、工具和多模态输入调用。适合需要 input 数组、工具调用或图片输入的新版客户端。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `model` | body:string | 是 | 模型编码，例如 gpt-5.5 或 gpt-image-2。 |
| `input` | body:string\|array | 是 | 输入文本或结构化 message 数组。 |
| `tools` | body:array | 否 | 工具列表，例如 image_generation。 |
| `include` | body:array | 否 | 需要额外返回的字段，平台仅支持已公开兼容字段。 |
| `stream` | body:boolean | 否 | 是否使用 SSE 流式返回。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `id` | string | 是 | 响应对象 ID。 |
| `output` | array | 是 | 模型输出项，可能包含 message、tool call 或生成结果。 |
| `output_text` | string | 否 | 聚合后的文本输出。 |
| `usage` | object | 否 | 模型用量，包含 input/output token。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/v1/responses" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"model":"gpt-5.5","input":"用一句话介绍 DataJion"}'
```

### 响应样例

```json
{
  "id": "resp_xxx",
  "object": "response",
  "output": [{"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "DataJion 是统一接入多家模型的平台。"}]}],
  "usage": {"input_tokens": 10, "output_tokens": 16, "total_tokens": 26}
}
```

### 注意事项

- 官方不支持的 include 值会返回明确错误；图片生成结果建议按公开文档中支持的接口形态调用。

## Images Generations

`POST /v1/images/generations`

协议：OpenAI 兼容

按 OpenAI 兼容图片生成协议创建图片。适合纯文生图场景，返回图片 URL 或 base64 数据取决于上游模型能力。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `model` | body:string | 是 | 图片模型编码，例如 gpt-image-2。 |
| `prompt` | body:string | 是 | 图片生成提示词。 |
| `size` | body:string | 否 | 输出尺寸，例如 1024x1024、1536x1024、3840x2160。 |
| `quality` | body:string | 否 | 质量档位，例如 standard、high。 |
| `n` | body:number | 否 | 期望生成数量；按次计费时平台按一次请求处理。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `created` | number | 否 | 生成时间戳。 |
| `data[].url` | string | 否 | 生成图片的可访问 URL。 |
| `data[].b64_json` | string | 否 | base64 图片数据。 |
| `usage` | object | 否 | 图片 token 或请求用量。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/v1/images/generations" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"model":"gpt-image-2","prompt":"一间明亮的现代书房","size":"1024x1024"}'
```

### 响应样例

```json
{
  "created": 1780660000,
  "data": [{"url": "https://datajion.caihdata.com/public/v1/generated-assets/asset_xxx/content"}],
  "usage": {"image_tokens": 1024}
}
```

### 注意事项

- 如果请求未传 size 且上游未返回尺寸，用于计费的默认尺寸按平台公开规则处理。

## Images Edits

`POST /v1/images/edits`

协议：OpenAI 兼容

按 OpenAI 官方图片编辑接口上传参考图并生成编辑结果。支持 multipart 上传，也支持平台可解析的 file_id 场景。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `model` | form:string | 是 | 图片编辑模型编码，例如 gpt-image-2。 |
| `image` | form:file\|file_id | 是 | 参考图片，支持文件上传或平台 file_id。 |
| `prompt` | form:string | 是 | 编辑说明。 |
| `mask` | form:file\|file_id | 否 | 可选遮罩图。 |
| `size` | form:string | 否 | 输出尺寸。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `created` | number | 否 | 生成时间戳。 |
| `data[].url` | string | 否 | 生成图片 URL。 |
| `data[].b64_json` | string | 否 | base64 图片数据。 |
| `usage` | object | 否 | 图片生成用量。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/v1/images/edits" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -F "model=gpt-image-2" \
  -F "image=@reference.png" \
  -F "prompt=把人物换成电影级写实风格"
```

### 响应样例

```json
{
  "created": 1780660000,
  "data": [{"url": "https://datajion.caihdata.com/public/v1/generated-assets/asset_xxx/content"}],
  "usage": {"image_tokens": 7024}
}
```

### 注意事项

- JSON file_id 会由平台解析为上游可接受的图片输入；上游是否支持多图编辑以模型能力为准。

## Videos

`POST /v1/videos`

协议：OpenAI 视频生成

提交 OpenAI 兼容视频生成任务。创建接口返回任务 ID，调用方应轮询任务详情获取最终视频资产。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `model` | body:string | 是 | 视频模型编码。 |
| `prompt` | body:string | 是 | 视频生成提示词。 |
| `seconds` | body:number | 否 | 视频时长，未提供时平台按 5 秒处理。 |
| `size` | body:string | 否 | 分辨率，例如 1280x720。 |
| `image` | body:string | 否 | 图生视频参考图 URL、data URL 或 file_id。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `id` | string | 是 | 视频任务 ID。 |
| `status` | string | 是 | 任务状态，例如 queued、running、completed、failed。 |
| `model` | string | 否 | 实际使用模型。 |
| `output_assets` | array | 否 | 任务完成后的生成资产列表。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/v1/videos" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"model":"sora","prompt":"城市夜景延时摄影","seconds":5,"size":"1280x720"}'
```

### 响应样例

```json
{
  "id": "video_xxx",
  "status": "queued",
  "model": "sora",
  "output_assets": []
}
```

### 注意事项

- 异步视频任务不要把创建响应当作最终结果；需要轮询 GET /v1/videos/{video_id}。

## Anthropic 兼容

适用于 Anthropic Messages 协议和 Claude 兼容客户端。

## Messages

`POST /v1/messages`

协议：Anthropic 兼容

发送 Claude Messages 请求。适用于 Anthropic SDK、Claude 兼容客户端和使用 Messages 协议的 Agent 工具。

鉴权：
- `x-api-key: <YOUR_API_KEY>`
- `anthropic-version: 2023-06-01`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `x-api-key` | header:string | 是 | 平台 API Key，Anthropic Messages 协议使用该 header。 |
| `anthropic-version` | header:string | 是 | Anthropic 协议版本，推荐使用 2023-06-01。 |
| `model` | body:string | 是 | Claude 兼容模型编码。 |
| `messages` | body:array | 是 | 对话消息数组。 |
| `max_tokens` | body:number | 是 | 最大输出 token 数。 |
| `system` | body:string\|array | 否 | 系统提示词。 |
| `stream` | body:boolean | 否 | 是否使用 SSE 流式返回。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `id` | string | 是 | 消息响应 ID。 |
| `content[].text` | string | 是 | 模型回复文本。 |
| `stop_reason` | string | 否 | 停止原因。 |
| `usage.input_tokens` | number | 否 | 输入 token 数。 |
| `usage.output_tokens` | number | 否 | 输出 token 数。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/v1/messages" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-4","max_tokens":512,"messages":[{"role":"user","content":"你好"}]}'
```

### 响应样例

```json
{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "content": [{"type": "text", "text": "你好，我可以协助你使用 DataJion。"}],
  "usage": {"input_tokens": 10, "output_tokens": 18}
}
```

### 注意事项

- Anthropic 协议使用 x-api-key；不要同时混用 Authorization Bearer。

## Gemini 兼容

适用于 Gemini 原生 Generate Content 与 Gemini 图片生成协议。

## Generate Content

`POST /v1beta/models/{model}:generateContent`

协议：Gemini 原生

按 Gemini 原生协议发送文本或多模态内容。路径中的 model 决定实际调用的 Gemini 兼容模型。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `model` | path:string | 是 | 路径变量，例如 gemini-2.5-flash。 |
| `contents` | body:array | 是 | Gemini 原生 contents 数组。 |
| `generationConfig` | body:object | 否 | 生成配置，例如温度、最大输出、responseModalities。 |
| `systemInstruction` | body:object | 否 | 系统指令。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `candidates[].content.parts[]` | array | 是 | 模型输出内容片段。 |
| `candidates[].finishReason` | string | 否 | 结束原因。 |
| `usageMetadata.promptTokenCount` | number | 否 | 输入 token 数。 |
| `usageMetadata.totalTokenCount` | number | 否 | 总 token 数。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"contents":[{"role":"user","parts":[{"text":"你好"}]}]}'
```

### 响应样例

```json
{
  "candidates": [{"content": {"role": "model", "parts": [{"text": "你好，我可以帮你调用 Gemini 兼容接口。"}]}, "finishReason": "STOP"}],
  "usageMetadata": {"promptTokenCount": 8, "candidatesTokenCount": 16, "totalTokenCount": 24}
}
```

### 注意事项

- Gemini 原生接口保留官方字段命名，例如 contents、parts、generationConfig。

## Gemini 图片生成

`POST /v1beta/models/{model}:generateContent`

协议：Gemini 图片生成

通过 Gemini 原生 generateContent 请求图片输出。图片比例、尺寸和输出模态应放在 generationConfig 中。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `model` | path:string | 是 | 图片模型编码，例如 gemini-3.1-flash-image-preview。 |
| `contents` | body:array | 是 | 文本或多模态输入。 |
| `generationConfig.responseModalities` | body:string[] | 是 | 必须包含 IMAGE，通常同时包含 TEXT。 |
| `generationConfig.responseFormat.image.aspectRatio` | body:string | 否 | 图片比例，例如 ASPECT_RATIO_SIXTEEN_BY_NINE。 |
| `generationConfig.responseFormat.image.imageSize` | body:string | 否 | 图片尺寸档位，例如 IMAGE_SIZE_ONE_K。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `candidates[].content.parts[].text` | string | 否 | 模型返回的文本说明。 |
| `candidates[].content.parts[].inlineData` | object | 否 | 图片二进制数据，包含 mimeType 和 data。 |
| `usageMetadata` | object | 否 | Gemini 用量统计。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"contents":[{"role":"user","parts":[{"text":"生成一张 16:9 卧室场景图"}]}],"generationConfig":{"responseModalities":["TEXT","IMAGE"],"responseFormat":{"image":{"aspectRatio":"ASPECT_RATIO_SIXTEEN_BY_NINE","imageSize":"IMAGE_SIZE_ONE_K"}}}}'
```

### 响应样例

```json
{
  "candidates": [{"content": {"parts": [{"text": "已生成图片"}, {"inlineData": {"mimeType": "image/png", "data": "<base64>"}}]}}],
  "usageMetadata": {"totalTokenCount": 1200}
}
```

### 注意事项

- 若上游返回图片链接，平台会按生成资产能力转换为可取回的公开资产链接。

## 火山与百炼兼容

适用于火山方舟 Chat、Responses、图片、视频任务，以及百炼视频任务。

## 火山 Chat Completions

`POST /api/v3/chat/completions`

协议：火山方舟

按火山方舟 Chat 协议发送请求。适合希望保持火山方舟官方路径和字段的调用方。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `model` | body:string | 是 | 火山方舟模型编码。 |
| `messages` | body:array | 是 | Chat 消息数组。 |
| `stream` | body:boolean | 否 | 是否流式返回。 |
| `temperature` | body:number | 否 | 采样温度。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `id` | string | 是 | 响应 ID。 |
| `choices[].message.content` | string | 是 | 模型回复。 |
| `usage` | object | 否 | token 用量。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/api/v3/chat/completions" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"model":"doubao-seed-2-0-pro","messages":[{"role":"user","content":"你好"}]}'
```

### 响应样例

```json
{
  "id": "chatcmpl_xxx",
  "choices": [{"message": {"role": "assistant", "content": "你好。"}}],
  "usage": {"prompt_tokens": 8, "completion_tokens": 8, "total_tokens": 16}
}
```

### 注意事项

- 火山路径与 OpenAI 兼容路径分开，便于客户按官方 SDK 形态接入。

## 火山 Responses

`POST /api/v3/responses`

协议：火山方舟

按火山方舟 Responses 协议发送请求，适合火山方舟新版 Responses 形态。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `model` | body:string | 是 | 火山方舟模型编码。 |
| `input` | body:string\|array | 是 | 输入文本或结构化输入。 |
| `stream` | body:boolean | 否 | 是否流式返回。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `id` | string | 是 | 响应 ID。 |
| `output` | array | 是 | 输出项。 |
| `usage` | object | 否 | token 用量。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/api/v3/responses" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"model":"doubao-seed-2-0-pro","input":"你好"}'
```

### 响应样例

```json
{
  "id": "resp_xxx",
  "output": [{"type": "message", "content": [{"type": "output_text", "text": "你好。"}]}],
  "usage": {"input_tokens": 6, "output_tokens": 8, "total_tokens": 14}
}
```

### 注意事项

- Responses 形态适合统一多模态和工具输入，但字段仍遵循火山方舟兼容定义。

## 火山视频生成任务

`POST /api/v3/contents/generations/tasks`

协议：火山视频生成

创建火山方舟视频生成任务，任务完成后查询任务详情获取视频资产。适合 Seedance 等视频模型。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `model` | body:string | 是 | 视频模型编码，例如 doubao-seedance-2-0-pro。 |
| `content` | body:array | 是 | 文本、图片或视频输入内容。 |
| `duration` | body:number | 否 | 视频秒数，未提供时平台按公开规则回退。 |
| `resolution` | body:string | 否 | 分辨率档位，例如 720p、1080p。 |
| `ratio` | body:string | 否 | 画幅比例。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `id` | string | 是 | 平台任务 ID。 |
| `status` | string | 是 | 任务状态。 |
| `task_type` | string | 否 | 任务类型，例如 text_to_video 或 image_to_video。 |
| `output_assets` | array | 否 | 完成后返回的生成资产列表。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"model":"doubao-seedance-2-0-pro","content":[{"type":"text","text":"一个镜头缓慢推进的城市夜景"}],"duration":5,"resolution":"720p"}'
```

### 响应样例

```json
{
  "id": "cgt-20260605200534-hmx8g",
  "status": "queued",
  "task_type": "text_to_video",
  "output_assets": []
}
```

### 注意事项

- 异步任务失败会返回明确状态；安全策略失败等可由平台路由策略决定是否降级重试。

## 百炼视频生成任务

`POST /api/v1/video/generations/tasks`

协议：百炼视频生成

创建百炼视频生成任务，随后查询任务状态和输出。适合需要保持百炼原生任务字段的调用方。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `model` | body:string | 是 | 百炼视频模型编码。 |
| `prompt` | body:string | 是 | 视频生成提示词。 |
| `duration` | body:number | 否 | 视频秒数，默认按 5 秒处理。 |
| `resolution` | body:string | 否 | 分辨率档位。 |
| `input_image` | body:string | 否 | 图生视频参考图。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `output.task_id` | string | 是 | 百炼任务 ID 或平台映射任务 ID。 |
| `output.task_status` | string | 是 | 任务状态。 |
| `output.results` | array | 否 | 完成后的结果列表。 |
| `usage` | object | 否 | 上游返回的用量或平台补充用量。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/api/v1/video/generations/tasks" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"model":"wanx2.1-t2v-turbo","prompt":"海边日落航拍","duration":5,"resolution":"720p"}'
```

### 响应样例

```json
{
  "output": {"task_id": "task_xxx", "task_status": "PENDING", "results": []},
  "request_id": "req_xxx"
}
```

### 注意事项

- 查询任务时若上游返回分辨率、秒数和 token，平台优先使用查询结果作为计费事实。

## 平台文件与生成资产

平台统一 Asset Store 能力，覆盖 OpenAI file_id、分片上传和模型生成结果取回。它和火山方舟素材库不是同一套资源体系。

## 上传平台文件

`POST /v1/files`

协议：平台统一 Asset Store

上传文件并获得平台 file_id。file_id 可用于支持文件输入的 Responses、图片编辑等 OpenAI 兼容接口；文件实际存储在平台配置的对象存储中。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `purpose` | form:string | 是 | 文件用途，例如 assistants、vision、batch。 |
| `file` | form:file | 是 | 要上传的本地文件。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `id` | string | 是 | 平台 file_id。 |
| `object` | string | 是 | 固定为 file。 |
| `filename` | string | 是 | 原始文件名。 |
| `bytes` | number | 是 | 文件大小。 |
| `purpose` | string | 是 | 上传用途。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/v1/files" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -F "purpose=assistants" \
  -F "file=@input.png"
```

### 响应样例

```json
{
  "id": "file_xxx",
  "object": "file",
  "filename": "input.png",
  "bytes": 204800,
  "purpose": "assistants"
}
```

### 注意事项

- 这是平台文件 ID，不是火山方舟素材 AssetId；不能直接当作火山素材 ID 使用。

## 创建分片上传

`POST /v1/uploads`

协议：平台统一 Asset Store

创建分片上传会话，用于较大文件上传。客户端随后按 upload_id 上传 part 并完成上传，完成后得到平台 file_id。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `purpose` | body:string | 是 | 文件用途。 |
| `filename` | body:string | 是 | 文件名。 |
| `bytes` | body:number | 是 | 文件总字节数。 |
| `mime_type` | body:string | 是 | 文件 MIME 类型。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `id` | string | 是 | 上传会话 ID。 |
| `object` | string | 是 | 固定为 upload。 |
| `status` | string | 是 | 上传状态。 |
| `expires_at` | number | 否 | 上传会话过期时间戳。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/v1/uploads" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"purpose":"assistants","filename":"large.mov","bytes":10485760,"mime_type":"video/mp4"}'
```

### 响应样例

```json
{
  "id": "upload_xxx",
  "object": "upload",
  "status": "pending",
  "expires_at": 1780663600
}
```

### 注意事项

- 分片接口用于平台文件，不会在火山方舟素材库中自动创建素材组或素材。

## 取回生成资产

`GET /public/v1/generated-assets/{id}/content`

协议：平台统一 Asset Store

使用生成资产 ID 下载图片或视频内容。该接口用于取回平台异步任务、图片生成或视频生成产生的资产。

鉴权：
- `公开访问，按资产链接权限控制`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `id` | path:string | 是 | 生成资产 ID。 |
| `expires` | query:number | 否 | 签名链接过期时间戳，按资产链接权限控制。 |
| `signature` | query:string | 否 | 资产签名，按资产链接权限控制。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Content-Type` | header:string | 是 | 资产 MIME 类型，例如 image/png 或 video/mp4。 |
| `Content-Length` | header:number | 否 | 资产字节数。 |
| `body` | binary | 是 | 图片、视频或音频二进制内容。 |

### 请求样例

```bash
curl -L "https://datajion.caihdata.com/public/v1/generated-assets/asset_xxxxx/content" -o output.bin
```

### 响应样例

```text
HTTP/1.1 200 OK
Content-Type: image/png

<binary image content>
```

### 注意事项

- 生产资产链接可能带签名和过期时间；不要把过期链接长期写死在业务配置中。

## 火山方舟素材库

火山方舟官方素材组与素材协议。平台负责 API Key 鉴权、租户火山子项目凭据注入、ProjectName 自动补充和常用字段归一；返回结构保持火山 OpenAPI 的 Result 风格。

## 创建素材组

`POST /api/v3/assets/groups/create`

协议：火山方舟素材库

创建火山方舟素材组。平台会自动注入租户默认火山子项目的 ProjectName，并把 GroupType 固定为 AIGC；真人人像素材组不通过该接口创建。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `name 或 Name` | body:string | 是 | 素材组名称。 |
| `description 或 Description` | body:string | 否 | 素材组描述。 |
| `ProjectName` | body:string | 否 | 无需传入，平台根据 API Key 所属租户自动注入。 |
| `GroupType` | body:string | 否 | 无需传入，平台创建时固定为 AIGC。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Result.Id` | string | 是 | 火山方舟素材组 ID。 |
| `Result.Name` | string | 否 | 素材组名称。 |
| `Result.GroupType` | string | 否 | 素材组类型。 |
| `ResponseMetadata` | object | 否 | 火山 OpenAPI 元信息。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/api/v3/assets/groups/create" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"name":"角色素材组","description":"用于 Seedance 视频生成"}'
```

### 响应样例

```json
{
  "Result": {
    "Id": "group_xxx",
    "Name": "角色素材组",
    "GroupType": "AIGC"
  }
}
```

### 注意事项

- 素材组 ID 是火山方舟 GroupId，不是平台 file_id。

## 查询素材组列表

`POST /api/v3/assets/groups/list`

协议：火山方舟素材库

分页查询当前租户火山子项目下的素材组。默认只查 AIGC 素材组；如需查询真人人像等类型，可传 group_type 或 Filter.GroupType。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `page_number 或 PageNumber` | body:number | 否 | 页码，默认 1。 |
| `page_size 或 PageSize` | body:number | 否 | 每页数量。 |
| `group_type 或 GroupType 或 Filter.GroupType` | body:string | 否 | 素材组类型，未传时默认 AIGC。 |
| `Filter` | body:object | 否 | 火山方舟过滤条件，平台会自动补充 ProjectName。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Result.Items[]` | array | 是 | 素材组列表。 |
| `Result.Items[].Id` | string | 是 | 素材组 ID。 |
| `Result.Items[].Name` | string | 否 | 素材组名称。 |
| `Result.Items[].GroupType` | string | 否 | 素材组类型。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/api/v3/assets/groups/list" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"page_number":1,"page_size":20}'
```

### 响应样例

```json
{
  "Result": {
    "Items": [
      {"Id": "group_xxx", "Name": "角色素材组", "GroupType": "AIGC"}
    ]
  }
}
```

### 注意事项

- 该接口返回火山素材组列表，不返回平台统一 Asset Store 文件。

## 获取素材组详情

`POST /api/v3/assets/groups/get`

协议：火山方舟素材库

按素材组 ID 获取火山方舟素材组详情。平台会自动注入 ProjectName。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `id 或 Id` | body:string | 是 | 素材组 ID。 |
| `ProjectName` | body:string | 否 | 无需传入，平台自动注入。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Result.Id` | string | 是 | 素材组 ID。 |
| `Result.Name` | string | 否 | 素材组名称。 |
| `Result.Description` | string | 否 | 素材组描述。 |
| `Result.GroupType` | string | 否 | 素材组类型。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/api/v3/assets/groups/get" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"id":"group_xxx"}'
```

### 响应样例

```json
{
  "Result": {
    "Id": "group_xxx",
    "Name": "角色素材组",
    "Description": "用于 Seedance 视频生成",
    "GroupType": "AIGC"
  }
}
```

### 注意事项

- 只能读取当前 API Key 所属租户火山子项目下可见的素材组。

## 更新素材组

`POST /api/v3/assets/groups/update`

协议：火山方舟素材库

更新火山方舟素材组名称或描述。平台会自动注入 ProjectName。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `id 或 Id` | body:string | 是 | 素材组 ID。 |
| `name 或 Name` | body:string | 否 | 新的素材组名称。 |
| `description 或 Description` | body:string | 否 | 新的素材组描述。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Result.Id` | string | 是 | 素材组 ID。 |
| `Result.Name` | string | 否 | 更新后的名称。 |
| `ResponseMetadata` | object | 否 | 火山 OpenAPI 元信息。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/api/v3/assets/groups/update" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"id":"group_xxx","name":"新角色素材组"}'
```

### 响应样例

```json
{
  "Result": {
    "Id": "group_xxx",
    "Name": "新角色素材组"
  }
}
```

### 注意事项

- 更新只影响火山方舟素材组，不会改动平台统一 Asset Store 文件。

## 删除素材组

`POST /api/v3/assets/groups/delete`

协议：火山方舟素材库

删除火山方舟素材组。删除前请确认组内素材不再被业务任务引用。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `id 或 Id` | body:string | 是 | 素材组 ID。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Result` | object | 否 | 火山方舟删除结果。 |
| `ResponseMetadata` | object | 否 | 火山 OpenAPI 元信息。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/api/v3/assets/groups/delete" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"id":"group_xxx"}'
```

### 响应样例

```json
{
  "Result": {
    "Id": "group_xxx"
  }
}
```

### 注意事项

- 该接口删除的是火山方舟素材组，不会删除平台生成资产下载链接。

## 创建素材

`POST /api/v3/assets/create`

协议：火山方舟素材库

向火山方舟素材组添加图片、视频或音频素材。平台支持 snake_case 简写并归一为火山字段，例如 group_id -> GroupId、asset_type -> AssetType、url -> URL。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `group_id 或 GroupId` | body:string | 是 | 火山方舟素材组 ID。 |
| `name 或 Name` | body:string | 是 | 素材名称。 |
| `url 或 URL` | body:string | 是 | 素材源文件 URL，火山方舟需要可访问该地址。 |
| `asset_type 或 AssetType` | body:string | 是 | 素材类型，例如 Image、Video、Audio。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Result.Id` | string | 是 | 火山方舟素材 ID。 |
| `Result.GroupId` | string | 是 | 所属火山素材组 ID。 |
| `Result.AssetType` | string | 否 | 素材类型。 |
| `Result.Status` | string | 否 | 素材处理状态。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/api/v3/assets/create" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"group_id":"group_xxx","name":"角色正面照","url":"https://example.com/photo.jpg","asset_type":"Image"}'
```

### 响应样例

```json
{
  "Result": {
    "Id": "asset_xxx",
    "GroupId": "group_xxx",
    "Name": "角色正面照",
    "AssetType": "Image",
    "Status": "Processing"
  }
}
```

### 注意事项

- 素材 ID 是火山方舟 AssetId，可在支持素材引用的火山任务中使用；它不同于平台 file_id。

## 查询素材列表

`POST /api/v3/assets/list`

协议：火山方舟素材库

分页查询火山方舟素材。平台会把顶层 group_id、GroupId、group_ids、GroupIds 归一到 Filter.GroupIds，避免上游忽略分组过滤。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `group_id 或 GroupId` | body:string | 否 | 按单个素材组过滤。 |
| `group_ids 或 GroupIds 或 Filter.GroupIds` | body:string[] | 否 | 按多个素材组过滤。 |
| `statuses 或 Statuses` | body:string[] | 否 | 素材状态过滤，例如 Active、Processing。 |
| `page_number 或 PageNumber` | body:number | 否 | 页码，默认 1。 |
| `page_size 或 PageSize` | body:number | 否 | 每页数量，默认 10。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Result.Items[]` | array | 是 | 素材列表。 |
| `Result.Items[].Id` | string | 是 | 素材 ID。 |
| `Result.Items[].GroupId` | string | 是 | 素材组 ID。 |
| `Result.Items[].Status` | string | 否 | 素材状态。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/api/v3/assets/list" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"group_id":"group_xxx","statuses":["Active"],"page_number":1,"page_size":10}'
```

### 响应样例

```json
{
  "Result": {
    "Items": [
      {"Id": "asset_xxx", "GroupId": "group_xxx", "Name": "角色正面照", "Status": "Active"}
    ]
  }
}
```

### 注意事项

- 未传 GroupType 时默认按 AIGC 查询；如果需要真人素材组，传 group_type 或 Filter.GroupType。

## 获取素材详情

`POST /api/v3/assets/get`

协议：火山方舟素材库

按素材 ID 获取火山方舟素材详情。平台会自动注入 ProjectName。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `id 或 Id` | body:string | 是 | 素材 ID。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Result.Id` | string | 是 | 素材 ID。 |
| `Result.GroupId` | string | 否 | 素材组 ID。 |
| `Result.URL` | string | 否 | 素材源 URL 或上游可见 URL。 |
| `Result.Status` | string | 否 | 素材状态。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/api/v3/assets/get" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"id":"asset_xxx"}'
```

### 响应样例

```json
{
  "Result": {
    "Id": "asset_xxx",
    "GroupId": "group_xxx",
    "Name": "角色正面照",
    "URL": "https://example.com/photo.jpg",
    "Status": "Active"
  }
}
```

### 注意事项

- 该详情来自火山方舟素材库，不代表平台对象存储中的文件详情。

## 更新素材

`POST /api/v3/assets/update`

协议：火山方舟素材库

更新火山方舟素材名称、描述或上游支持的其他素材字段。平台会自动注入 ProjectName。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `id 或 Id` | body:string | 是 | 素材 ID。 |
| `name 或 Name` | body:string | 否 | 新的素材名称。 |
| `description 或 Description` | body:string | 否 | 新的素材描述。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Result.Id` | string | 是 | 素材 ID。 |
| `Result.Name` | string | 否 | 更新后的名称。 |
| `ResponseMetadata` | object | 否 | 火山 OpenAPI 元信息。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/api/v3/assets/update" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"id":"asset_xxx","name":"角色正面照-新版"}'
```

### 响应样例

```json
{
  "Result": {
    "Id": "asset_xxx",
    "Name": "角色正面照-新版"
  }
}
```

### 注意事项

- 更新素材不会改写平台统一 Asset Store 中已上传的 OpenAI file_id 文件。

## 删除素材

`POST /api/v3/assets/delete`

协议：火山方舟素材库

删除火山方舟素材。删除后，依赖该素材 ID 的火山任务可能无法继续复用该素材。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `id 或 Id` | body:string | 是 | 素材 ID。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Result` | object | 否 | 火山方舟删除结果。 |
| `ResponseMetadata` | object | 否 | 火山 OpenAPI 元信息。 |

### 请求样例

```bash
curl -X POST "https://datajion.caihdata.com/api/v3/assets/delete" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"id":"asset_xxx"}'
```

### 响应样例

```json
{
  "Result": {
    "Id": "asset_xxx"
  }
}
```

### 注意事项

- 该删除动作只针对火山方舟素材库。平台生成资产链接和 OpenAI file_id 需走平台文件与生成资产接口处理。

## 用量与费用

客户可以用 API Key 查询余额、配额和 Claude Code 兼容用量。

## 余额查询

`GET /user/balance`

协议：客户查询

查询当前 API Key 所属应用和租户的余额或配额摘要。适合客户在自己的系统中展示账户可用额度。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `request body` | none | 否 | 该接口不需要请求体。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `balance` | number | 否 | 账户余额，单位由返回 currency 决定。 |
| `currency` | string | 否 | 余额币种，例如 cny。 |
| `quota` | object | 否 | 订阅或额度摘要。 |
| `tenant_id` | string | 否 | 所属租户 ID。 |

### 请求样例

```bash
curl "https://datajion.caihdata.com/user/balance" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

### 响应样例

```json
{
  "balance": 128.5,
  "currency": "cny",
  "quota": {"available": true},
  "tenant_id": "tenant_xxx"
}
```

### 注意事项

- 不含运营端成本字段；客户只能查询自身 API Key 可见的余额信息。

## New API 兼容自查询

`GET /api/user/self`

协议：客户查询

返回 cc-switch、New API 模板可识别的额度结构，便于客户工具读取当前账号状态。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `request body` | none | 否 | 该接口不需要请求体。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `id` | string | 否 | 当前 API Key 或用户标识。 |
| `quota` | number | 否 | 兼容格式额度。 |
| `used_quota` | number | 否 | 兼容格式已用额度。 |
| `status` | string\|number | 否 | 账号状态。 |

### 请求样例

```bash
curl "https://datajion.caihdata.com/api/user/self" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

### 响应样例

```json
{
  "id": "app_key_xxx",
  "quota": 1000000,
  "used_quota": 12000,
  "status": "active"
}
```

### 注意事项

- 该接口是客户侧兼容层，不返回平台内部管理信息。

## Claude Code 用量查询

`GET /api/oauth/usage`

协议：客户查询

返回 Claude Code 兼容用量结构，用于展示短窗口和长窗口配额。适合 Claude Code 兼容代理或客户自建工具读取。

鉴权：
- `Authorization: Bearer <YOUR_API_KEY>`

### 请求参数

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `Authorization` | header:string | 是 | 平台 API Key，格式为 Bearer <YOUR_API_KEY>。 |
| `request body` | none | 否 | 该接口不需要请求体。 |

### 响应字段

| 名称 | 类型 | 必填/必返 | 说明 |
|---|---|---|---|
| `utilization.five_hour` | object | 否 | 短窗口用量，字段名保持 Claude Code 兼容。 |
| `utilization.seven_day` | object | 否 | 长窗口用量，字段名保持 Claude Code 兼容。 |
| `resets_at` | string | 否 | 窗口重置时间。 |
| `limits` | object | 否 | 当前订阅或配额限制。 |

### 请求样例

```bash
curl "https://datajion.caihdata.com/api/oauth/usage" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

### 响应样例

```json
{
  "utilization": {
    "five_hour": {"used": 12.5, "limit": 55, "resets_at": "2026-06-05T16:00:00Z"},
    "seven_day": {"used": 120, "limit": 350, "resets_at": "2026-06-12T00:00:00Z"}
  }
}
```

### 注意事项

- 字段名是客户端兼容约定，不代表后台配置窗口一定严格等于 5 小时或 7 天。