# 接口文档

通过 OpenAI 兼容接口，快速接入 AI 创作能力。  
用你熟悉的方式，连接图像、视频与文本模型。

如果你是 AI Agent，请阅读 [Markdown 版本](/docs.md)。

OpenAI 兼容 多模型支持 快速接入

<a id="quickstart"></a>



## 快速开始

只需三步，即可发起你的第一次 API 调用。

<a id="api-key"></a>



### 1 获取 API Key

创建应用专属密钥，  
连接你需要的模型。

[前往获取 API Key](/api-keys)

<a id="base-url"></a>



### 2 复制接口地址

将 Base URL 配置到客户端，  
使用 OpenAI 兼容接口。

`https://xiaolu.hututuit.online/v1`

### 3 开始调用

选择可用模型，填入你的密钥，  
让创意从代码中发生。

[查看调用示例](#first-request)

<a id="user-balance"></a>



## 账户余额

先确认账户可用积分

GET `/v1/user/balance` 查询账户余额

使用 API Key，获取账户余额与累计成功消费。

请求示例

```
curl 'https://xiaolu.hututuit.online/v1/user/balance' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

响应示例 200 OK

```
{
  "object": "user.balance",
  "balance": 120.5,
  "used": 30,
  "total": 150.5
}
```

`balance` 为可用积分；`used` 为累计成功消费，失败退款不计入；`total` 为两者之和，不代表累计充值。生成中的预扣费已从余额扣除，成功后才计入消费。

<a id="first-request"></a>



## 发起第一次调用

选择语言，复制示例，将 YOUR\_API\_KEY 替换为你的密钥。

[更多示例](#examples)

 **文生图**  `POST /v1/images/generations`

```bash
curl https://xiaolu.hututuit.online/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-gpt-image-2",
    "prompt": "a corgi running in a golden wheat field, cinematic",
    "size": "1024x1024",
    "response_format": "url"
  }'
```

```python
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://xiaolu.hututuit.online/v1")
result = client.images.generate(
    model="firefly-gpt-image-2",
    prompt="a corgi running in a golden wheat field, cinematic",
    size="1024x1024",
    response_format="url",
)
print(result.data[0].url)
```

调用前请携带密钥读取 [GET /v1/models](#models) 确认可用模型；生成请求会按所选模型计费。

<a id="endpoint-index"></a>



API REFERENCE

## 接口目录

点击查看参数与示例

[GET `/v1/user/balance` 账户余额 API Key 所属用户的剩余积分和累计成功消费](#user-balance)

 

[GET `/v1/models` 模型列表 读取可用模型与支持协议](#models)

 

[GET `/admin/api/model-status` 模型状态 公开状态快照，无需 API Key](#model-status)

 

[POST `/v1/chat/completions` 文本对话 Chat Completions，支持上游接口的 JSON / SSE](#text-completions)

 

[POST `/v1/responses` Responses 文本 文本、工具调用、流式输出和会话续接](#text-completions)

 

[POST `/v1/messages` Messages 文本 Anthropic 原生请求与响应](#text-completions)

 

[POST `/v1beta/models/{model}:generateContent` Gemini 文本 Gemini 原生请求；流式使用 streamGenerateContent?alt=sse](#text-completions)

 

[POST `/v1/images/generations` 文生图 JSON，同步返回图像结果](#image-generation)

 

[GET `/v1/image-results/{id}` 读取公开图像 URL 模式返回的临时图像地址](#image-results)

 

[GET `/v1/images/{id}/content` 读取图像内容 需要 API Key 的图像二进制](#image-content)

 

[POST `/v1/images/edits` 图生图 multipart/form-data，上传参考图](#image-edit)

 

[POST `/v1/responses` 异步生图 后台任务，适合长任务和参考图](#background-image)

 

[GET `/v1/responses/{id}` 查询异步任务 读取状态与 output\[0\].result](#responses-status)

 

[POST `/v1/responses/{id}/cancel` 取消异步任务 取消尚未完成的任务](#responses-status)

 

[POST `/v1/videos` 创建视频任务 JSON 或 multipart，立即返回 queued](#video-generation)

 

[GET `/v1/videos/{id}` 查询视频状态 轮询至 completed 或 failed](#video-status)

 

[GET `/v1/videos/{id}/content` 下载视频 返回 mp4 原始二进制](#video-content)

<a id="gateway-access"></a>



ACCESS

## 密钥与计费

在 [API 密钥](/api-keys) 页面为不同应用创建密钥，按需设置累计消费上限、有效期和模型价格保护。所有密钥共享账户余额。模型与价格统一由管理员配置，无需选择分组。

OpenAI 接口使用 `Authorization: Bearer YOUR_API_KEY`；Messages 也接受 `x-api-key`，Gemini 也接受 `x-goog-api-key`。密钥列表支持显示和复制完整值，脱敏预览不能用于调用。可用模型及协议以携带该密钥请求 `GET /v1/models` 的结果为准。

模型价格保护：图片按每张价格，视频按分辨率和时长计算的单次总价，按次文本按调用价格检查；按 token 文本可分别限制输入、输出和各类缓存单价（积分 / 百万 token），全部长上下文阶梯均须满足上限。未设置的模型或留空项不限价，0 仅接受免费调用，等于上限允许调用。超价返回 HTTP 400，错误码 `price_limit_exceeded`（Gemini 位于 `error.reason`），并附模型、价格项、当前价与上限；不调用上游、不扣费。排队任务提交和执行前均会检查，计费方式变更也会拒绝，需重新设置保护规则。

文本支持按 token 或按次计费，积分保留八位小数。按 token 请求会先预留额度，再按实际输入、输出、缓存用量结算；预留不是最终费用。停止或中断的请求自动按已收到的用量结算；上游未提供用量时自动释放预留、不扣费，可在“积分流水”查看明细并按密钥筛选。原生文本请求可传 `Idempotency-Key`；重复提交返回 409 和已有请求编号，不会重复扣费。

<a id="models"></a>



03 · MODEL CATALOG

## 模型目录

GET /v1/models · 39 个匹配

下表保留已有模型的媒体能力与参考价格。各模型的可用接口及文本价格请在 [模型广场](/model-square) 查看；调用前携带密钥读取 `GET /v1/models` 确认访问范围。

 MODEL | 类型 | 能力 | 参考 | 价格 |
| --- | --- | --- | --- | --- |
 `gemini-nano-banana-2.1` 最新香蕉模型 | 图像 | 1K · 2K · 4K 比例 1:1 · 16:9 · 9:16 · 3:2 · 8:1 · 3:4 · 1:4 · 1:8 · 21:9 · 3:1 支持图生图 | 最多 6 张 | 8.8 积分 |
 `seedance-2.5` 可过人脸，支持最多 30 张参考图和 10 段 MP3 音频，固定生成音轨。 | 视频 | 480p · 720p 比例 21:9 · 16:9 · 4:3 · 1:1 · 3:4 · 9:16 时长 4-25秒 | 参考图 | 55–88 积分/秒 |
 `veo-3.1-1080p` 最新一代gemini视频模型，支持1080p | 视频 | 1080p 比例 16:9 · 9:16 时长 8秒 | 参考图 · 首尾帧 | 13.2 积分/秒 |
 `grok-imagine-video-1.5` 最新grok视频模型，支持1080p、15秒视频 | 视频 | 480p · 720p · 1080p 比例 1:1 · 16:9 · 9:16 · 3:2 · 4:3 · 3:4 · 2:3 时长 1-15秒 | 参考图 | 8.8–16.5 积分/秒 |
 `nano-banana-pro` 适合品牌海报、信息图和需要保持主体一致的系列设计 | 图像 | 1K · 2K · 4K 比例 1:1 · 1:4 · 1:8 · 2:3 · 3:2 · 3:4 · 4:1 · 4:3 · 4:5 · 5:4 · 8:1 · 9:16 · 16:9 · 21:9 支持图生图 | 最多 6 张 | 8.8 积分 |
 `seedream-5.0-pro` | 图像 | 1K · 2K 比例 1:1 · 16:9 · 9:16 · 4:3 · 4:1 · 3:4 · 2:3 · 3:2 仅文生图 | — | 9.9 积分 |
 `gpt-6-sol` 通用文本处理与提示词优化 | 文本 | 非流式 Chat Completions 按次计费 | — | 输入 66 / 输出 330 积分/百万 token |
 `gpt-6.1-sol` 通用文本处理与提示词优化 | 文本 | 非流式 Chat Completions 按次计费 | — | 输入 66 / 输出 330 积分/百万 token |
 `kimi-k3` 通用文本处理与提示词优化 | 文本 | 非流式 Chat Completions 按次计费 | — | 输入 880 / 输出 4400 积分/百万 token |
 `gemini-3.7-flash` 通用文本处理与提示词优化 | 文本 | 非流式 Chat Completions 按次计费 | — | 输入 24.75 / 输出 123.75 积分/百万 token |
 `gemini-3.8-flash` 通用文本处理与提示词优化 | 文本 | 非流式 Chat Completions 按次计费 | — | 输入 24.75 / 输出 123.75 积分/百万 token |
 `glm-5.3` 通用文本处理与提示词优化 | 文本 | 非流式 Chat Completions 按次计费 | — | 输入 484 / 输出 1694 积分/百万 token |
 `deepseek-v4.1-flash` 通用文本处理与提示词优化 | 文本 | 非流式 Chat Completions 按次计费 | — | 输入 88 / 输出 352 积分/百万 token |
 `claude-opus-5` 通用文本处理与提示词优化 | 文本 | 非流式 Chat Completions 按次计费 | — | 输入 550 / 输出 2750 积分/百万 token |
 `claude-fable-5-1` 通用文本处理与提示词优化 | 文本 | 非流式 Chat Completions 按次计费 | — | 输入 1100 / 输出 5500 积分/百万 token |
 `claude-sonnet-5-5` 通用文本处理与提示词优化 | 文本 | 非流式 Chat Completions 按次计费 | — | 输入 220 / 输出 1100 积分/百万 token |
 `claude-opus-5-5` 通用文本处理与提示词优化 | 文本 | 非流式 Chat Completions 按次计费 | — | 输入 440 / 输出 2200 积分/百万 token |
 `gemini-3.6-flash` 识图用户用的比较多 | 文本 | 非流式 Chat Completions 按次计费 | — | 输入 49.5 / 输出 247.5 积分/百万 token |
 `gpt-6-astra` 通用文本处理与提示词优化 | 文本 | 非流式 Chat Completions 按次计费 | — | 输入 330 / 输出 1650 积分/百万 token |
 `wan3.0-video-prime` 单次生成30秒长视频 | 视频 | 480p · 720p · 1080p 比例 16:9 · 9:16 · 1:1 · 4:3 · 3:4 · 21:9 时长 2-30秒 | 参考图 · 首尾帧 | 33–52.8 积分/秒 |
 `minimax-h3-optimized` 自部署版本，做了电商漫剧优化 | 视频 | 768p 比例 16:9 · 9:16 · 1:1 · 4:3 · 3:4 · 21:9 时长 4-15秒 | 参考图 · 首尾帧 | 11 积分/秒 |
 `veo-3.1-fast-1080p` | 视频 | 1080p 比例 16:9 · 9:16 时长 8秒 | 参考图 · 首尾帧 | 11 积分/秒 |
 `veo-3.1-fast` | 视频 | 720p 比例 16:9 · 9:16 时长 8秒 | 参考图 · 首尾帧 | 8.8 积分/秒 |
 `seedance-2.0-930` 会卡人脸，支持9张参考图，3个参考视频 | 视频 | 720p 比例 16:9 · 9:16 时长 15秒 | 参考图 | 33 积分/秒 |
 `grok-imagine-video` 最高支持720P，支持15秒视频 | 视频 | 480p · 720p 比例 1:1 · 16:9 · 9:16 · 3:2 · 4:3 · 3:4 · 2:3 时长 1-15秒 · 14个档位 | 参考图 | 8.8 积分/秒 |
 `seedance-2.0-900` 会卡人脸，支持9张参考图，不支持参考视频和音频 | 视频 | 720p 比例 16:9 · 9:16 时长 15秒 | 参考图 | 22 积分/秒 |
 `gpt-image-2.5-sunburst-firefly` 适合主题海报、品牌主视觉与故事插画。 | 图像 | 1K · 2K · 4K 比例 1:1 · 16:9 · 9:16 · 5:4 · 4:3 · 3:2 · 3:1 · 3:4 支持图生图 | 最多 10 张 | 5.5 积分 |
 `gpt-auto` 通用文字助手，可以辅助整理绘图提示词 | 文本 | 非流式 Chat Completions 按次计费 | — | 1.1 积分/次 |
 `gpt-image-2.5-flare-firefly` 适合商品背景、宣传配图和同一主题的多版创意探索。 | 图像 | 1K · 2K · 4K 比例 1:1 · 16:9 · 9:16 · 4:3 · 3:2 · 3:4 · 2:3 支持图生图 | 最多 10 张 | 5.5 积分 |
 `gpt-image-2.5-flare` 适合创意草图、社交配图与不同构图方案的探索 | 图像 | 1K 比例 1:1 · 16:9 · 9:16 · 5:4 · 4:3 · 3:2 · 4:5 · 3:4 支持图生图 | 最多 15 张 | 1.1 积分 |
 `gpt-image-2.5-sunburst` 适合包含人物、物件与场景要求的主题创作 | 图像 | 1K 比例 1:1 · 16:9 · 9:16 · 4:3 · 21:9 · 3:1 · 4:5 · 3:4 · 1:4 支持图生图 | 最多 15 张 | 1.1 积分 |
 `gpt-image-2.5` 适合日常设计、文章配图和视觉灵感探索 | 图像 | 1K 比例 1:1 · 16:9 · 9:16 · 5:4 · 4:3 · 3:2 · 21:9 · 8:1 · 4:5 · 3:4 · 2:3 · 1:3 支持图生图 | 最多 15 张 | 1.1 积分 |
 `grok-image` 适合风格化插画、社交内容配图和创意场景探索。 | 图像 | 1K · 2K 比例 1:1 · 2:3 · 3:2 · 3:4 · 4:3 · 9:16 · 16:9 支持图生图 | 最多 3 张 | 2.2 积分 |
 `gpt-image-2-high` 高质量 gpt-image-2 模型 | 图像 | 1K · 2K · 4K 比例 1:1 · 5:4 · 9:16 · 21:9 · 16:9 · 4:3 · 3:2 · 4:5 · 3:4 · 2:3 支持图生图 | 最多 6 张 | 9.9 积分 |
 `veo-3.1` | 视频 | 720p 比例 16:9 · 9:16 时长 8秒 | 参考图 · 首尾帧 支持音轨 | 11 积分/秒 |
 `gpt-image-2` 适合概念设计、商品配图，以及根据具体要求修改已有画面 | 图像 | 1K 比例 1:1 · 16:9 · 9:16 · 4:3 · 3:4 支持图生图 | 最多 15 张 | 1.1 积分 |
 `nano-banana-2` 适合日常设计、电商配图和同一主体的多场景创作 | 图像 | 1K · 2K · 4K 比例 1:1 · 1:4 · 1:8 · 2:3 · 3:2 · 3:4 · 4:1 · 4:3 · 4:5 · 5:4 · 8:1 · 9:16 · 16:9 · 21:9 支持图生图 | 最多 6 张 | 6.6 积分 |
 `firefly-gpt-image-2` 适合需要指定输出清晰度的设计任务 | 图像 | 1K · 2K · 4K 比例 1:1 · 5:4 · 9:16 · 21:9 · 16:9 · 4:3 · 3:2 · 4:5 · 3:4 · 2:3 支持图生图 | 最多 10 张 | 4.4 积分 |
 `grok-video` 网页反代，只支持6秒视频 | 视频 | 720p 比例 2:3 · 3:2 · 1:1 · 9:16 · 16:9 时长 6秒 | 无 | 2.2 积分/秒 |

实际扣费以请求参数、模型价格与账户规则为准。

<a id="model-status"></a>



03.1 · PUBLIC STATUS

## 模型状态

`GET /admin/api/model-status 无需 Key`

返回当前模型的公开可用性快照，适合状态页、自动切换模型和调用前健康检查。该接口不需要登录，也不需要 `Authorization` 请求头。

公开接口，可直接跨页面调用。服务端状态快照最多缓存 5 分钟；客户端可按需轮询，建议间隔不少于 60 秒。

operational degraded outage maintenance unknown

 字段 | 类型 | 说明 |
| --- | --- | --- |
 `data` | `array` | 当前公开模型的状态列表。 |
 `data[].model_id` | `string` | 模型配置 ID。 |
 `data[].name` | `string` | 模型显示名称。 |
 `data[].alias` | `string` | 公开别名；未设置时省略。 |
 `data[].description` | `string` | 公开模型说明；为空时省略。 |
 `data[].type` | `string` | 模型类型：text、image 或 video。 |
 `data[].provider` | `string` | 模型所属服务类型。 |
 `data[].prices` | `object` | 公开价格表：图片按分辨率、视频按分辨率每秒、文本按次展示积分价格；按 token 模型以 text\_pricing 中的输入、输出、缓存价格为准。 |
 `data[].status` | `string` | operational、degraded、outage、maintenance 或 unknown。 |
 `data[].status_reason` | `string` | 当前状态的简要原因。 |
 `data[].availability_7d` | `number \| null` | 最近 7 天可用率，范围 0 到 1；无数据时为 null。 |
 `data[].samples_7d` | `integer` | 最近 7 天计入可用率的样本数量。 |
 `data[].avg_ms` | `integer \| null` | 最近 24 小时平均处理耗时，单位毫秒。 |
 `data[].last_checked_at` | `string \| null` | 最近检测时间，RFC 3339 格式。 |
 `data[].updated_at` | `string` | 该模型状态记录的更新时间，RFC 3339 格式。 |
 `updated_at` | `string` | 本次公开状态快照的更新时间。 |

 **模型状态**  `GET /admin/api/model-status · 无需 API Key`

```bash
curl https://xiaolu.hututuit.online/admin/api/model-status
```

<a id="text-completions"></a>



04 · TEXT

## 文本对话

`POST /v1/chat/completions`

支持模型声明的原生协议：Chat Completions、Responses、Messages 或 Gemini。上游接口保留工具调用和 SSE 事件，具体功能由模型与上游支持情况决定。Chat Completions 的非流式响应包含 `choices[].message`。

Responses 使用 `POST /v1/responses`，请求包含 `model` 与 `input`；Messages 使用 `POST /v1/messages`，请求包含 `model`、`messages` 与 `max_tokens`，可携带 `anthropic-version`。两者传 `stream: true` 请求 SSE。Gemini 使用 `POST /v1beta/models/{model}:generateContent` 与 `contents`，流式路径为 `:streamGenerateContent?alt=sse`。

文本 Responses 返回本站响应 ID。查询、取消、删除和 `input_items` 使用该 ID；续接时填入 `previous_response_id`，请求会回到原上游账号。模型必须声明对应协议，不能仅更换接口路径来转换协议。

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `model` | `string` | 是 | 文本模型 ID，可从模型目录获取。 |
 `messages` | `array` | 是 | 对话消息数组；上游文本模型支持其协议允许的图文内容和工具消息，具体能力由模型决定。 |
 `temperature` | `number` | 否 | 采样温度，范围 0 到 2。 |
 `top_p` | `number` | 否 | 核采样参数，范围 0 到 1。 |
 `max_tokens` | `integer` | 否 | 最大输出 token 数，必须大于 0。 |
 `max_completion_tokens` | `integer` | 否 | 最大完成 token 数，必须大于 0。 |
 `response_format` | `object` | 否 | 响应格式要求；是否支持取决于所选文本模型。 |
 `stream` | `boolean` | 否 | 上游文本模型传 true 返回 SSE；原有按次模型以实际接口支持为准。 |
 `tools / tool_choice` | `array / string / object` | 否 | 上游文本模型透传工具定义和选择参数，是否支持由模型决定。 |

 **文本对话**  `POST /v1/chat/completions`

```bash
curl https://xiaolu.hututuit.online/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "用三句话介绍这项服务。"}
    ],
    "temperature": 0.7,
    "stream": false
  }'
```

```python
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://xiaolu.hututuit.online/v1")
result = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "用三句话介绍这项服务。"},
    ],
    temperature=0.7,
)
print(result.choices[0].message.content)
```

<a id="image-generation"></a>



05 · IMAGE

## 文生图

`POST /v1/images/generations`

发送提示词后同步返回图像结果。使用 `response_format: "url"` 获取临时地址，或使用 `b64_json` 获取内联内容。

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `model` | `string` | 是 | 公开模型 ID，可从模型目录获取。 |
 `prompt` | `string` | 是 | 描述期望图像的文字提示。 |
 `n` | `integer` | 否 | 当前每次生成 1 张图片，n 默认 1；JSON 请求不接受其他数量。 |
 `size` | `string` | 否 | WIDTHxHEIGHT；必须落在模型支持的比例与分辨率内。 |
 `resolution` | `string` | 否 | 可选分辨率档位；优先使用模型目录和 size 对照表。 |
 `quality` | `string` | 否 | low、medium、high 或 auto；Adobe 图片模型透传给 custom 上游，省略时使用上游默认值。 |
 `background` | `string` | 否 | transparent 透明背景、opaque 不透明背景、auto 默认行为。支持 Adobe GPT Image 系列；其他兼容图片模型以其能力为准，不支持时返回 400。 |
 `response_format` | `string` | 否 | url 或 b64\_json；省略时使用后台配置的默认值。 |

 **文生图**  `POST /v1/images/generations`

```bash
curl https://xiaolu.hututuit.online/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-gpt-image-2",
    "prompt": "a corgi running in a golden wheat field, cinematic",
    "size": "1024x1024",
    "response_format": "url"
  }'
```

```python
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://xiaolu.hututuit.online/v1")
result = client.images.generate(
    model="firefly-gpt-image-2",
    prompt="a corgi running in a golden wheat field, cinematic",
    size="1024x1024",
    response_format="url",
)
print(result.data[0].url)
```

<a id="transparent-background"></a>



### 透明背景

文生图与图生图

选择 Adobe GPT Image 图片模型，例如 `gpt-image-2-high`，在请求中传 `"background": "transparent"`。图生图表单传 `background=transparent`；JSON 编辑同样支持该字段。`opaque` 请求不透明背景，省略或传 `auto` 使用模型默认行为。

提示词应明确主体独立、无桌面或场景背景；完整场景描述可能只让画面边缘透明。`response_format` 只决定返回 URL 还是 Base64，两种方式都保留原图透明度。保存时保留 PNG 等支持透明度的原始格式；不要转换成 JPEG，`transparent` 与 `output_format: "jpeg"` 同传会返回 400。

 **生成透明背景图片**  `POST /v1/images/generations`

```bash
curl 'https://xiaolu.hututuit.online/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "gpt-image-2-high",
  "prompt": "一只独立的红色陶瓷杯，完整主体，透明背景，无桌面、无环境场景",
  "background": "transparent",
  "response_format": "b64_json"
}'
```

 **编辑为透明背景**  `POST /v1/images/edits · multipart`

```bash
curl 'https://xiaolu.hututuit.online/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'model=gpt-image-2-high' \
  -F 'prompt=保留图中主体，去掉背景，输出透明背景图片' \
  -F 'image=@input.png' \
  -F 'background=transparent' \
  -F 'response_format=b64_json'
```

使用 Base64 响应时，将 `data[0].b64_json` 解码后保存图片。此参数用于 `/v1/images/generations` 和 `/v1/images/edits`；`/v1/responses` 的布尔值 `background: true` 表示后台执行，当前不提供透明背景选项。

<a id="image-results"></a>



05.1 · IMAGE RESULT

### 读取公开图像

`GET /v1/image-results/{id}`

当图像结果使用 URL 格式并落在本站临时存储时，可直接访问该地址，不需要 API Key。Bunny 结果在下一个 UTC 零点到期，本地结果最长保留 24 小时；以返回的 `expires_at` 为准。同时支持 `HEAD` 和 `Range`。

<a id="image-content"></a>



05.2 · IMAGE CONTENT

### 读取授权图像内容

`GET /v1/images/{id}/content`

用于需要 API Key 校验的图像结果，返回图像原始二进制。请求必须携带生成该结果的 API Key。

<a id="image-edit"></a>



06 · IMAGE EDIT

## 图生图

`POST /v1/images/edits`

文件上传使用 `multipart/form-data`；Grok / xAI 的 JSON 编辑方式见[附录 B](#grok-compat)。至少提供一张图片；只有模型目录标记为支持图生图的模型才可调用。

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `image / image[]` | `file` | 是 | multipart 文件；至少一张，多张图片可重复 image 或 image\[\] 字段。 |
 `model` | `string` | 是 | 必须是模型目录标记为支持图生图的图片模型。 |
 `prompt` | `string` | 是 | 描述编辑目标或参考关系。 |
 `n` | `integer` | 否 | 当前每次生成 1 张图片，n 默认 1；JSON 请求不接受其他数量。 |
 `size` | `string` | 否 | WIDTHxHEIGHT；以模型目录中的能力为准。 |
 `resolution` | `string` | 否 | 可选分辨率档位；未声明时不要自行套用其他模型的尺寸表。 |
 `quality` | `string` | 否 | 与文生图接口相同。 |
 `background` | `string` | 否 | 与文生图相同；透明背景使用表单字段 background=transparent，JSON 编辑使用 "background": "transparent"。 |
 `response_format` | `string` | 否 | url 或 b64\_json；URL 无需再次携带 API Key。 |

 **图生图**  `POST /v1/images/edits · multipart`

```bash
curl https://xiaolu.hututuit.online/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model="gemini-nano-banana-2.1" \
  -F prompt="把这张图改成电影感光影" \
  -F image=@input.png \
  -F response_format=b64_json
# 多张参考图：重复 -F image=@reference.png
```

```python
import base64
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://xiaolu.hututuit.online/v1")
result = client.images.edit(
    model="gemini-nano-banana-2.1",
    image=open("input.png", "rb"),
    prompt="把这张图改成电影感光影",
    response_format="b64_json",
)
with open("output.png", "wb") as output:
    output.write(base64.b64decode(result.data[0].b64_json))
```

<a id="background-image"></a>



07 · BACKGROUND JOB

## 异步生图

`POST /v1/responses`

这是公开的 Responses API 子集：仅用于后台图像任务，必须传 `background: true`，提交后通过任务 ID 轮询。

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `model` | `string` | 是 | 图片模型 ID。 |
 `background` | `boolean` | 是 | 必须为 true；当前公开的 Responses API 仅用于后台图像任务。 |
 `input` | `string \| array` | 是 | 提示词字符串，或包含 input\_text / input\_image 的消息数组。 |
 `input_image.image_url` | `string` | 否 | HTTP(S) URL 或 data:image/...;base64,...；不支持 file\_id。 |
 `size / quality` | `string` | 否 | 与同步图像接口使用相同的模型能力约束。 |
 `response_format` | `string` | 否 | url 或 b64\_json；完成结果格式与同步接口一致。 |
 `Idempotency-Key` | `header` | 否 | 用于避免后台任务重复提交；冲突时返回 422。 |

1  **提交**  返回 queued

2  **轮询**  queued → in\_progress

3  **取结果**  completed / failed / cancelled

 **异步生图**  `POST /v1/responses · 轮询 · 取消`

```bash
RESPONSE_ID=$(curl -s https://xiaolu.hututuit.online/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: customer-order-123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "background": true,
    "response_format": "url",
    "input": [{"role":"user","content":[
      {"type":"input_text","text":"保持主体，改成电影光影"},
      {"type":"input_image","image_url":"https://example.com/reference.png"}
    ]}]
  }' | jq -r .id)

# 轮询 queued / in_progress，直到 completed
curl https://xiaolu.hututuit.online/v1/responses/$RESPONSE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

# 尚未完成时可以取消
curl -X POST https://xiaolu.hututuit.online/v1/responses/$RESPONSE_ID/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<a id="responses-status"></a>



08 · RESPONSES

## 查询和取消异步任务

GET /v1/responses/{id} · POST /cancel

GET `/v1/responses/{id}` 读取状态、错误和 output\[0\].result

POST `/v1/responses/{id}/cancel` 取消尚未完成的任务

queued in\_progress completed failed cancelled

完成结果位于 `output[0].result`。如果使用 `response_format: "url"`，结果是临时 URL；使用 `b64_json` 时结果是内联内容。

<a id="video-generation"></a>



09 · VIDEO

## 视频生成

`POST /v1/videos`

视频生成是异步任务。创建后立即返回 `queued`，轮询状态，完成后读取 URL 或下载内容。

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `model` | `string` | 是 | 视频模型 ID。 |
 `prompt` | `string` | 文生视频必填 | 描述视频内容、动作、镜头和风格。 |
 `seconds / duration` | `string \| number` | 是 | 生成时长；duration 是兼容别名，必须是模型支持的时长。 |
 `size` | `string` | 否 | WIDTHxHEIGHT；短边决定分辨率档位，同时决定比例。 |
 `aspect_ratio` | `string` | 否 | 也可直接传比例，例如 16:9、9:16；size 优先映射。 |
 `resolution` | `string` | 否 | 也可直接传 720p、1080p 等模型支持的档位。 |
 `reference_mode` | `string` | 否 | asset=普通参考图；frame=首尾帧。字段本身也会触发自动识别。 |
 `reference_images` | `string[] \| file[]` | 否 | 普通参考图；JSON 用 URL、Data URI 或原始 Base64，multipart 可重复字段。 |
 `start_frame / end_frame` | `string \| file` | 否 | 首尾帧；end\_frame 必须搭配 start\_frame，且不能与普通参考图混用。 |
 `reference_videos` | `string[] \| file[]` | 否 | 参考视频；数量和格式以模型公开能力为准。 |
 `audio_reference(s)` | `string \| string[] \| file[]` | 否 | 参考音频；必须搭配模型支持的普通图像或视频参考。 |
 `audio` | `boolean` | 否 | 控制输出音轨；仅对支持该能力的模型生效。 |
 `response_format` | `string` | 否 | 仅支持 url；完成态返回公开临时 URL 和 expires\_at。 |

 **视频生成**  `POST /v1/videos · 创建 · 轮询 · 下载`

```bash
curl https://xiaolu.hututuit.online/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "a paper boat sailing down a rainy street, cinematic",
    "seconds": "4",
    "size": "1120x480",
    "response_format": "url"
  }'

# 轮询状态，完成后读取 url
curl https://xiaolu.hututuit.online/v1/videos/<VIDEO_ID> \
  -H "Authorization: Bearer YOUR_API_KEY"
curl '<RETURNED_URL>' -o output.mp4
```

```python
import time
import requests

base = "https://xiaolu.hututuit.online/v1"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
job = requests.post(f"{base}/videos", headers=headers, json={
    "model": "seedance-2.5",
    "prompt": "a paper boat sailing down a rainy street",
    "seconds": "4",
    "size": "1120x480",
    "response_format": "url",
}).json()

while True:
    status = requests.get(f"{base}/videos/{job['id']}", headers=headers).json()
    if status["status"] in ("completed", "failed"):
        break
    time.sleep(5)

if status["status"] == "completed":
    open("output.mp4", "wb").write(requests.get(status["url"]).content)
```

<a id="video-status"></a>



09.1 · VIDEO STATUS

### 查询视频状态

`GET /v1/videos/{id}`

状态通常按 `queued → in_progress → completed` 变化，也可能进入 `failed`。只有完成后才能读取视频内容。

<a id="video-content"></a>



09.2 · VIDEO CONTENT

### 下载视频

`GET /v1/videos/{id}/content`

完成任务后返回  **mp4 原始二进制** ，不是 Base64，也不是 JSON。任务未完成时返回 409。

<a id="formats"></a>



10 · FORMATS

## 尺寸与格式

按模型能力选择

 **`firefly-gpt-image-2` 图片尺寸**  下表只适用于该图片模型。建议直接使用表内原生尺寸，最长边不超过 3840。

 比例 | 1K | 2K | 4K |
| --- | --- | --- | --- |
 1:1 · 方 | `1024x1024` | `2048x2048` | `2880x2880` |
 5:4 · 横 | `1120x896` | `2240x1792` | `3200x2560` |
 4:3 · 横 | `1152x864` | `2304x1728` | `3264x2448` |
 3:2 · 横 | `1248x832` | `2496x1664` | `3504x2336` |
 16:9 · 横 | `1280x720` | `2560x1440` | `3840x2160` |
 21:9 · 超宽 | `1456x624` | `3024x1296` | `3696x1584` |
 4:5 · 竖 | `896x1120` | `1792x2240` | `2560x3200` |
 3:4 · 竖 | `864x1152` | `1728x2304` | `2448x3264` |
 2:3 · 竖 | `832x1248` | `1664x2496` | `2336x3504` |
 9:16 · 竖 | `720x1280` | `1440x2560` | `2160x3840` |

例如：2K · 16:9 传 `"size": "2560x1440"`。其他图片模型请以模型目录中的比例和分辨率为准。

 **视频 `size` 对照**  短边决定 720p / 1080p / 1440p / 2160p 档位。实际档位仍必须在对应视频模型的公开能力内。

 比例 | 720p | 1080p | 1440p | 2160p |
| --- | --- | --- | --- | --- |
 21:9 · 超宽 | `1680x720` | `2520x1080` | `3360x1440` | `5040x2160` |
 16:9 · 横 | `1280x720` | `1920x1080` | `2560x1440` | `3840x2160` |
 9:16 · 竖 | `720x1280` | `1080x1920` | `1440x2560` | `2160x3840` |
 1:1 · 方 | `720x720` | `1080x1080` | `1440x1440` | `2160x2160` |
 4:3 · 横 | `960x720` | `1440x1080` | `1920x1440` | `2880x2160` |
 3:4 · 竖 | `720x960` | `1080x1440` | `1440x1920` | `2160x2880` |

例如：720p 的 16:9 横版传 `"size": "1280x720"`；竖版 9:16 传 `"720x1280"`。

<a id="examples"></a>



11 · EXAMPLES

## 调用示例

示例中的模型 ID 会跟随实时目录

 **列出模型**  `GET /v1/models`

```bash
curl https://xiaolu.hututuit.online/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"
```

 **模型状态**  `GET /admin/api/model-status · 无需 API Key`

```bash
curl https://xiaolu.hututuit.online/admin/api/model-status
```

 **文本对话**  `POST /v1/chat/completions`

```bash
curl https://xiaolu.hututuit.online/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "用三句话介绍这项服务。"}
    ],
    "temperature": 0.7,
    "stream": false
  }'
```

```python
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://xiaolu.hututuit.online/v1")
result = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "用三句话介绍这项服务。"},
    ],
    temperature=0.7,
)
print(result.choices[0].message.content)
```

 **文生图**  `POST /v1/images/generations`

```bash
curl https://xiaolu.hututuit.online/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-gpt-image-2",
    "prompt": "a corgi running in a golden wheat field, cinematic",
    "size": "1024x1024",
    "response_format": "url"
  }'
```

```python
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://xiaolu.hututuit.online/v1")
result = client.images.generate(
    model="firefly-gpt-image-2",
    prompt="a corgi running in a golden wheat field, cinematic",
    size="1024x1024",
    response_format="url",
)
print(result.data[0].url)
```

 **图生图**  `POST /v1/images/edits · multipart`

```bash
curl https://xiaolu.hututuit.online/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model="gemini-nano-banana-2.1" \
  -F prompt="把这张图改成电影感光影" \
  -F image=@input.png \
  -F response_format=b64_json
# 多张参考图：重复 -F image=@reference.png
```

```python
import base64
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://xiaolu.hututuit.online/v1")
result = client.images.edit(
    model="gemini-nano-banana-2.1",
    image=open("input.png", "rb"),
    prompt="把这张图改成电影感光影",
    response_format="b64_json",
)
with open("output.png", "wb") as output:
    output.write(base64.b64decode(result.data[0].b64_json))
```

 **异步生图**  `POST /v1/responses · 轮询 · 取消`

```bash
RESPONSE_ID=$(curl -s https://xiaolu.hututuit.online/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: customer-order-123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "background": true,
    "response_format": "url",
    "input": [{"role":"user","content":[
      {"type":"input_text","text":"保持主体，改成电影光影"},
      {"type":"input_image","image_url":"https://example.com/reference.png"}
    ]}]
  }' | jq -r .id)

# 轮询 queued / in_progress，直到 completed
curl https://xiaolu.hututuit.online/v1/responses/$RESPONSE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

# 尚未完成时可以取消
curl -X POST https://xiaolu.hututuit.online/v1/responses/$RESPONSE_ID/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"
```

 **视频生成**  `POST /v1/videos · 创建 · 轮询 · 下载`

```bash
curl https://xiaolu.hututuit.online/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "a paper boat sailing down a rainy street, cinematic",
    "seconds": "4",
    "size": "1120x480",
    "response_format": "url"
  }'

# 轮询状态，完成后读取 url
curl https://xiaolu.hututuit.online/v1/videos/<VIDEO_ID> \
  -H "Authorization: Bearer YOUR_API_KEY"
curl '<RETURNED_URL>' -o output.mp4
```

```python
import time
import requests

base = "https://xiaolu.hututuit.online/v1"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
job = requests.post(f"{base}/videos", headers=headers, json={
    "model": "seedance-2.5",
    "prompt": "a paper boat sailing down a rainy street",
    "seconds": "4",
    "size": "1120x480",
    "response_format": "url",
}).json()

while True:
    status = requests.get(f"{base}/videos/{job['id']}", headers=headers).json()
    if status["status"] in ("completed", "failed"):
        break
    time.sleep(5)

if status["status"] == "completed":
    open("output.mp4", "wb").write(requests.get(status["url"]).content)
```

<a id="contract"></a>



12 · CONTRACT

## 响应、计费与错误

 **图像** 

`url` 返回公开临时 URL，`b64_json` 返回内联 Base64。两种格式均建立生成记录，返回 `id` 和 `expires_at`。使用 API Key 请求 `GET /v1/images/{id}` 可查询状态及有效图片地址；过期后仍可查询生成记录。Bunny 图片在下一个 UTC 零点到期。

 **异步图像** 

参考图使用 `input_image.image_url`，支持 HTTP(S) URL 或 data URL，不提供 Files API 或 `file_id`。全局参考图上限为 15，模型还可能有更低限制。

 **视频** 

创建、轮询、下载分为三步。显式传 `response_format: "url"` 时完成态包含 `url` 和 `expires_at`；否则使用 `/content`。

 **计费** 

生成前预扣积分；图像或视频上游失败会自动退回。视频按所选分辨率的每秒单价乘以 `seconds` 计算。

 **文本** 

支持按次或按实际 token 结算，返回模型支持协议的原生 JSON / SSE。输入、输出和缓存分别计价；调用结束后未取得用量时自动释放预留，不扣费。

400 参数缺失、不支持、未定价或提示词被拒

401 API Key 无效，或上游授权/额度需要重新处理

402 积分不足或密钥消费额度不足

403 密钥已停用、过期或无效

404 模型、任务或结果不存在

409 内容尚未完成，或文本幂等请求已存在

413 参考媒体过大

422 图片 URL 无效或幂等键冲突

429 并发或队列已满，请稍后重试

501 当前模型不支持该能力

502 上游执行失败

503 无可用上游账号、文本模型尚未定价或上游暂时不可用

<a id="gemini-images"></a>



APPENDIX A · GEMINI COMPATIBILITY

## 附录 A：Gemini 兼容接口

生图与编辑

本附录介绍 Gemini 兼容接口，使用 Gemini GenerateContent 格式调用本站图片模型，API 地址为 `https://xiaolu.hututuit.online/v1beta`。

GET `/v1beta/models` 支持 Gemini 协议的模型列表

GET `/v1beta/models/{model}` 读取单个 Gemini 模型

POST `/v1beta/models/{model}:generateContent` 生图与编辑，返回内联图片

POST `/v1beta/models/{model}:streamGenerateContent?alt=sse` SSE 生图，出图后返回完整结果事件

API Key 使用本站密钥，可放在 `x-goog-api-key`、`Authorization: Bearer` 或 `?key=` 中。响应图片位于 `candidates[].content.parts[].inlineData`。

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `contents` | `array` | 是 | 图文消息，使用 user / model 角色；最多 128 条。 |
 `contents[].parts[].text` | `string` | 是 | 提示词。图生图时在同一 parts 数组中加入 inlineData。 |
 `contents[].parts[].inlineData` | `object` | 否 | 参考图：mimeType 与纯 base64 data；支持 PNG、JPEG、WebP、GIF，每张不超过 25 MiB，数量受模型配置限制。 |
 `generationConfig.responseModalities` | `array` | 否 | 支持 \["IMAGE"\] 或 \["TEXT", "IMAGE"\]；省略时请求图文输出。 |
 `generationConfig.imageConfig.aspectRatio` | `string` | 否 | 如 1:1、16:9；显式值必须在模型支持范围内。 |
 `generationConfig.imageConfig.imageSize` | `string` | 否 | 1K / 2K / 4K，省略按 1K 校验与计费；不支持的档位直接报错。 |
 `generationConfig.candidateCount` | `integer` | 否 | 当前仅支持 1。按一次请求及所选分辨率计费，候选数不是图片张数。 |

单次请求上限 100 MiB。多轮编辑需模型配置了 Gemini 上游；将上一轮完整的 model content（包括 thoughtSignature）加入下一轮 contents。基础图片渠道支持单轮文字和参考图；不支持的高级请求会明确报错。当前不提供 Files API、countTokens、工具调用或 512 分辨率。

流式地址为 `/v1beta/models/{model}:streamGenerateContent?alt=sse`：等待期间发送 SSE 心跳，出图完成后发送一个完整的 Gemini 结果事件并结束连接。无图或内容拒绝退回生图费用，并保留 Gemini 的 promptFeedback / finishReason；不伪造 token 用量。

sub2api 接入：选择 Gemini 平台与 API Key 账号，Base URL 填本站根地址 `https://xiaolu.hututuit.online`（不加 /v1 或 /v1beta），填写本站 Key，并将测试模型和模型映射设为本站实际开放的图片模型。

 **Gemini 兼容 · 生图与编辑**  `POST /v1beta/models/{model}:generateContent`

```bash
curl 'https://xiaolu.hututuit.online/v1beta/models/firefly-gpt-image-2:generateContent' \
  -H 'x-goog-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "生成一只坐在窗边的橘猫，摄影风格"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "TEXT",
      "IMAGE"
    ],
    "imageConfig": {
      "aspectRatio": "1:1",
      "imageSize": "1K"
    }
  }
}'
```

<a id="grok-compat"></a>



APPENDIX B · GROK COMPATIBILITY

## 附录 B：Grok（xAI）兼容接口

生图、编辑与视频

本站提供 Grok / xAI 通用图片与视频接口，支持文生图、JSON 图片编辑、文生视频和参考图生视频，可供 sub2api 等兼容下游调用。API 地址为 `https://xiaolu.hututuit.online/v1`，使用本站 API Key，通过 `Authorization: Bearer YOUR_API_KEY` 鉴权。

POST `/v1/images/generations` Grok / xAI JSON 文生图

POST `/v1/images/edits` Grok / xAI JSON 图片编辑，兼容 sub2api

POST `/v1/videos/generations` Grok / xAI 风格的视频生成，返回 request\_id

GET `/v1/videos/{request_id}` 查询生成状态与结果地址

GET `/v1/videos/{request_id}/content` 携带 API Key 下载 MP4

请求使用 `application/json`；图片请求体上限 100 MiB，视频请求体上限 50 MiB。参考图支持 PNG、JPEG、WebP，每张最多 25 MiB，张数还受模型限制。模型、时长、比例和分辨率以本站模型目录为准。

### 图片生成与编辑

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `model` | `string` | 是 | 本站已启用的图片模型 ID，可通过 /v1/models 获取；以本站模型目录为准。 |
 `prompt` | `string` | 是 | 生成或编辑图片的文字指令。 |
 `n` | `integer` | 否 | 默认 1，目前仅支持 1；其他值会报错，不会多扣费或静默少返回。 |
 `aspect_ratio` | `string` | 否 | 如 1:1、16:9，需符合模型能力；auto 由上游决定，默认使用模型比例。 |
 `resolution` | `string` | 否 | 1k / 2k，默认 1k；需启用对应计费档位，也接受 1K / 2K。 |
 `response_format` | `string` | 否 | url 或 b64\_json；Grok 请求默认 url，结果位于 data\[\].url 或 data\[\].b64\_json。 |
 `image.url / images[].url` | `string` | 编辑必填 | 单图使用 image，多图使用 images；支持公网 HTTP(S) URL、data:image/...;base64,...，以及 image\_url 别名。 |

 **Grok 兼容 · 文生图**  `POST /v1/images/generations`

```bash
curl 'https://xiaolu.hututuit.online/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "grok-image",
  "prompt": "生成一只坐在窗边的橘猫，摄影风格",
  "n": 1,
  "aspect_ratio": "1:1",
  "resolution": "1k",
  "response_format": "url"
}'
```

 **Grok 兼容 · JSON 图片编辑**  `POST /v1/images/edits`

```bash
curl 'https://xiaolu.hututuit.online/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "grok-image",
  "prompt": "保持主体不变，把背景改成海边",
  "image": {
    "url": "data:image/png;base64,REPLACE_WITH_IMAGE_BASE64"
  },
  "n": 1,
  "resolution": "1k",
  "response_format": "b64_json"
}'
```

将示例占位符替换为图片 Base64，或把 `image.url` 换成实际公网图片地址；多图使用 `"images":[{"url":"..."},{"url":"..."}]`。支持 sub2api 转换后的 `image=images[0]` 格式。

### 视频生成、查询与下载

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `model` | `string` | 是 | 本站已启用的视频模型 ID；兼容名称 grok-imagine-video 调用本站 grok-video 模型。 |
 `prompt` | `string` | 文生视频必填 | 描述视频内容、动作和镜头；提供参考图时可省略。 |
 `duration` | `integer / string` | 否 | 1–15 的整数秒数，默认 8 秒，也接受 seconds 别名；实际可用值以模型目录为准。 |
 `aspect_ratio` | `string` | 否 | 画面比例，默认 16:9；需使用模型支持的比例。 |
 `resolution` | `string` | 否 | 分辨率，默认 480p；实际可用档位以模型目录为准。 |
 `image.url` | `string` | 否 | 图生视频首帧，支持公网 HTTP(S) URL、data:image/...;base64,... 或纯 Base64。 |
 `reference_images[].url` | `string` | 否 | 多张参考图，格式与 image.url 相同；数量和能力受模型限制。 |
 `size` | `string` | 否 | 兼容 WIDTHxHEIGHT，补充未显式指定的比例和分辨率。 |

 **Grok 兼容 · 创建视频任务**  `POST /v1/videos/generations`

```bash
curl 'https://xiaolu.hututuit.online/v1/videos/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "grok-imagine-video-1.5",
  "prompt": "海浪轻拍沙滩，镜头缓慢推进，电影质感",
  "duration": 1,
  "aspect_ratio": "1:1",
  "resolution": "480p"
}'
```

提交成功返回 `{"request_id":"任务ID"}`，随后查询同一任务，直至 `done`、`failed` 或 `expired`。仅通过 `/v1/videos/generations` 创建的任务使用这套状态格式。

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `request_id` | `string` | — | 提交成功返回的任务 ID，用于查询和下载。 |
 `status` | `string` | — | pending=生成中；done=完成；failed=失败；expired=临时结果已过期。 |
 `progress` | `integer` | — | 本站任务阶段进度，完成时为 100。 |
 `video.url` | `string` | — | 完成后返回可直接下载的 MP4 地址，含临时下载凭证，有效期 24 小时；不要删除查询参数。 |
 `url / download_url` | `string` | — | 完成时返回本站 /content 地址；下载时必须携带生成该任务的 API Key。 |
 `video.duration` | `integer` | — | 完成视频的时长，单位为秒。 |
 `error.message` | `string` | — | 生成失败时的错误说明。 |

完成结果包含 `"status":"done","video":{"url":"...","duration":6,"respect_moderation":true}`。可直接下载 `video.url`；也可像 sub2api 一样通过携带 API Key 的 `/content` 路径下载。

 **Grok 兼容 · 查询与下载**  `GET /v1/videos/{request_id} · GET /content`

```bash
# 将 REQUEST_ID 替换为提交响应中的 request_id
curl 'https://xiaolu.hututuit.online/v1/videos/REQUEST_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

# 查询结果为 status: "done" 后下载
curl 'https://xiaolu.hututuit.online/v1/videos/REQUEST_ID/content' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -o output.mp4
```

sub2api 接入：选择 Grok / xAI 的 API Key 账号，填写本站地址与密钥，配置本站已启用的图片、视频模型及模型映射；确保最终路径与本附录一致。旧版 Responses 连通性探测不生成媒体；sub2api 的图片/视频测试会实际生成并计费。

custom 上游接入：选择“Grok 兼容”，填写 xAI 官方或 sub2api 的 URL 与 API Key，选择本地模型并映射到上游模型名称。内置模型要直接使用该上游时选择“接管”。sub2api 部分版本的视频测试固定使用 6 秒 / 480p，需要配置支持此档位的模型。当前兼容上述媒体接口；批量生图、图片流式输出、mask、Files API、视频编辑/续接、自定义存储和音频参考尚未支持。[xAI 官方协议参考](https://docs.x.ai/developers/rest-api-reference/inference/videos)。

<a id="seedance"></a>



APPENDIX C · SEEDANCE / ARK

## 附录 C：Seedance（Ark 任务接口）

Sub2API 可作为上游接入

使用本站 API Key 调用 Ark 兼容任务接口。Base URL 为 `https://xiaolu.hututuit.online/api/v3`，创建任务使用 `content[]`，成功结果位于 `content.video_url`。模型、时长、比例、分辨率和参考能力以[模型目录](#models)为准。

 **Seedance · 创建任务**  `POST /api/v3/contents/generations/tasks`

```bash
curl 'https://xiaolu.hututuit.online/api/v3/contents/generations/tasks' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "海浪轻轻拍打沙滩，镜头缓慢推进"
    }
  ],
  "duration": 4,
  "ratio": "21:9",
  "resolution": "480p"
}'
```

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `model` | `string` | 是 | 本站公开的视频模型 ID；时长、参考能力与价格以模型目录为准。 |
 `content` | `array` | 是 | 非空数组，最多 32 项。文字使用 {"type":"text","text":"提示词"}；多个文字项按换行合并。 |
 `content[].image_url` | `object` | 否 | type=image\_url，image\_url={"url":"公网 URL 或 Data URI"}。role 为 first\_frame（默认）、last\_frame 或 reference\_image；尾帧须搭配首帧。 |
 `content[].video_url / audio_url` | `object` | 否 | type=video\_url 或 audio\_url，对应字段为 {"url":"…"}。role 分别为 reference\_video / reference\_audio，可省略；支持 HTTP(S) 或对应媒体的 Data URI。 |
 `duration` | `integer` | 否 | 正整数秒，默认 5；必须在模型支持范围内，不支持 -1 自动时长。 |
 `ratio / resolution` | `string` | 否 | 例如 16:9 / 720p；默认比例 16:9，分辨率采用模型默认档位。建议按模型目录显式填写。 |
 `generate_audio` | `boolean` | 否 | 控制生成音轨，仅用于声明支持此能力的模型。 |

普通参考与首尾帧互斥；音频参考按模型要求搭配视觉参考。当前支持上表字段；callback\_url、seed、draft、watermark、return\_last\_frame、tools 等扩展参数会返回 400，不会被静默忽略。

### 查询、下载与删除

 **Seedance · 查询与下载**  `GET /api/v3/contents/generations/tasks/{id}`

```bash
# 创建返回 {"id":"任务ID"}；替换 TASK_ID，查询至 succeeded / failed / expired
curl 'https://xiaolu.hututuit.online/api/v3/contents/generations/tasks/TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

# succeeded 后，复制响应 content.video_url 的完整地址（含 media_token）
curl 'VIDEO_URL' -o video.mp4

# 可选：删除已结束的任务，返回 204
curl -X DELETE 'https://xiaolu.hututuit.online/api/v3/contents/generations/tasks/TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

状态为 `queued / running / succeeded / failed / expired`。创建、查询和删除需要本站 API Key，任务按本站用户隔离；同一用户的密钥可查询其任务。视频链接包含临时下载凭证，无需额外密钥，有效期为生成完成后 24 小时。查询已有任务不重复扣费；删除仅支持已结束任务，不退还成功任务费用，且会撤销该任务的 API 查询与下载权限。运行中删除返回 409，暂不支持主动取消。

 **完成响应示例 · 本次扣除 3 积分**  `200 OK`

```json
{
  "id": "TASK_ID",
  "model": "seedance-2.5",
  "status": "succeeded",
  "content": {
    "video_url": "https://xiaolu.hututuit.online/api/v3/contents/generations/tasks/TASK_ID/content?media_token=TEMPORARY_TOKEN"
  },
  "usage": {
    "completion_tokens": 3000,
    "total_tokens": 3000
  },
  "billing": {
    "unit": "credit_equivalent",
    "credits": 3,
    "units_per_credit": 1000,
    "measured_tokens": false
  }
}
```

### 在你的 Sub2API 中接入本站

使用支持 Seedance 的 Sub2API v0.2.7 或更新版本，新增  **OpenAI 平台 → API Key 账号** ，勾选  **Seedance (Ark)** 。Base URL 填 `https://xiaolu.hututuit.online/api/v3`，API Key 填本站密钥。配置本站视频模型及模型映射，加入可用分组，并开启分组的“允许图片生成”媒体权限。

 **计费单位：** 本站按模型价格预扣积分，失败退款。为兼容 Sub2API 的 Seedance 结算，成功响应的 `usage.completion_tokens` 按实际扣费积分 × 1000 折算，四舍五入为整数；这是兼容计费单位，并非上游真实推理 token。`billing.measured_tokens=false` 明确标注来源，重复查询返回相同单位数。

Sub2API 按成功查询的 usage 结算。若希望每个本站积分向下游收取 P 个货币单位，将输出价格设置为  **1000 × P / 百万 token** ，并考虑分组倍率。例：每积分收取 0.01，则设置 10 / 百万 token，3 积分对应 3000 单位，基础费用为 0.03。客户端必须查询到 succeeded，并及时保存视频；不要通过重复创建来重试查询。

同时提供 `/v3`、`/v1` 和无版本前缀的任务路由别名；Sub2API 上游地址建议使用上述 `/api/v3` 地址。未提供任务列表、回调或完整 Ark 扩展能力。错误格式为 `{"error":{"code":"…","message":"…"}}`。

### 管理员：连接 Seedance custom 上游

本站管理员添加上游时选择  **Seedance (Ark)** ，填写 Sub2API 或 Ark 地址与密钥，选择视频模型并配置映射；内置模型直接走该连接时选择“接管”。账号池、模型路由与渠道健康调度由 Sub2API 管理。[Sub2API Seedance 协议说明](https://github.com/Wei-Shaw/sub2api/blob/v0.2.7/docs/seedance-api.md)。

<a id="minimax"></a>



APPENDIX D · MINIMAX / HAILUO

## 附录 D：MiniMax 原生视频接口

兼容 New API Hailuo 插件

New API 的 Hailuo Video 插件可以直接接入本站。上游地址填写 `https://xiaolu.hututuit.online`（不加 /v1 或 /v2），密钥使用本站 API Key。model 填写本站模型目录或 `/v1/models` 返回的实际模型 ID，例如 `minimax-h3-optimized`。v1、v2 均使用本站模型配置，查询结果保留本站模型 ID。

Hailuo Video 1.2.0 使用本站模型 ID 时会选择 v1 接口，可用于文生视频、首尾帧和主体参考。多模态 content\[\] 可直接请求本站 v2 接口；该版本插件仅为名称 MiniMax-H3 自动选择 v2，经它使用 v2 需调整插件的接口选择逻辑，model 仍填写本站模型 ID。

POST `/v1/video_generation` v1 创建：prompt、first\_frame\_image、last\_frame\_image、subject\_reference

GET `/v1/query/video_generation?task_id=TASK_ID` v1 查询：Queueing / Processing / Success / Fail；成功返回 file\_id

GET `/v1/files/retrieve?file_id=FILE_ID` 文件信息，返回 file.download\_url

GET `/v1/files/download?file_id=FILE_ID` 携带 API Key 下载 MP4，也支持 HEAD

POST `/v2/video_generation` H3 创建：content\[\]、duration、resolution、ratio

GET `/v2/query/video_generation/TASK_ID` H3 查询：task.status；成功结果位于 task.content.url

 **MiniMax H3 · 创建任务**  `POST /v2/video_generation`

```bash
curl 'https://xiaolu.hututuit.online/v2/video_generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-h3-optimized",
  "content": [
    {
      "type": "text",
      "text": "海浪轻拍沙滩，镜头缓慢推进"
    }
  ],
  "duration": 6,
  "resolution": "768P",
  "ratio": "16:9"
}'
```

创建返回 `{"task_id":"任务ID"}`。v2 查询状态为 `queued / running / succeeded / failed`，成功后直接下载 `task.content.url`，保留完整查询参数。v1 返回 `base_resp.status_code`，0 表示成功。查询与文件信息需要 Bearer API Key；结果链接自带临时凭证，最长有效 24 小时，过期后查询返回失败。

H3 优化版支持 4–15 整数秒、768P；720P 按原有兼容规则对应 768P。接口兼容不会增加模型能力，480P、2K 或未启用的 Hailuo 模型仍会被拒绝。v1 默认 6 秒，v2 默认 5 秒；分辨率省略时使用模型默认档位。

v2 的 `content[]` 支持 text、image\_url、video\_url、audio\_url。图片 role 为 first\_frame、last\_frame 或 reference\_image，视频和音频分别为 reference\_video、reference\_audio；首尾帧与素材参考互斥。图像参考支持公网地址、Data URI 或 Base64；视频、音频遵循模型素材限制。adaptive 根据第一张参考图选择最接近的支持比例；纯视频参考请显式填写 ratio。尾帧需要首帧，纯音频参考不支持。

可传 `Idempotency-Key` 防止重复创建和扣费。失败沿用本站退款和积分流水规则。暂不支持 callback\_url、水印、提示词优化或快速预处理；对应布尔选项可省略或设为 false，开启时会明确报错。未测量的输入时长和 token 用量不会伪造返回。

## 快捷导航

[**获取 API Key**  创建你的应用密钥](#api-key) [**接口地址**  复制客户端 Base URL](#base-url) [**示例代码**  复制即可开始调用](#first-request) [ **响应与错误**  计费规则与错误说明](#contract)

## 创作能力

[**图像生成**  文生图、图生图与透明背景](#image-generation) [**视频创作**  生成、查询与下载](#video-generation) [**文本对话**  多种协议与流式输出](#text-completions) [探索模型广场](/model-square)

## 本页导航

开始接入

[快速开始](#quickstart)[账户余额](#user-balance)[第一次调用](#first-request)[接口目录](#endpoint-index)[密钥与计费](#gateway-access)[模型目录](#models)[模型状态](#model-status)

生成与调用

[文本对话](#text-completions)[文生图](#image-generation)[透明背景](#transparent-background)[图生图](#image-edit)[异步生图](#background-image)[视频生成](#video-generation)

参考与兼容

[尺寸与格式](#formats)[调用示例](#examples)[响应与错误](#contract)[附录 · Gemini 兼容接口](#gemini-images)[附录 · Grok 兼容接口](#grok-compat)[附录 · Seedance 视频](#seedance)[附录 · MiniMax 视频](#minimax)

[ **让创意，即刻发生**  在模型体验中试试效果](/user)