feat(doc):补充参考文档，便于AI分析
This commit is contained in:
qian committed
1 parent
7ace16a42e
commit
79b6f390dd
22 files changed
+29875
No files matched your search
@@ -0,0 +1,261 @@
|
||||
# API 接口格式参考
|
||||
|
||||
本文档是 CLAUDE.md 中 API 接口规范的详细参考资料，包含完整的 JSON 示例、响应格式、错误类型映射等。开发时按需查阅。
|
||||
|
||||
## 统一响应格式详细示例
|
||||
|
||||
**适用范围**：`/api/admin/*`、`/api/tenant/*`、`/api/payment/*`、`/api/open/*`、`/api/status`。
|
||||
|
||||
### 字段说明
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `code` | int | `0` = 成功，非 `0` = 错误。标准 HTTP 错误直接用状态码（400/401/403/404/409/500），业务错误用 >= 10000 的自定义码 |
|
||||
| `message` | string | 用户可读的中文提示。成功时固定 `"ok"`，错误时描述具体原因，禁止暴露技术细节 |
|
||||
| `data` | any | 成功时为业务数据（对象/数组/字符串），错误时为 `null` |
|
||||
| `request_id` | string | 每个请求的唯一标识，贯穿全链路，用于日志追踪 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
// 成功（HTTP 200）
|
||||
{"code": 0, "message": "ok", "data": {"id": 1, "name": "张三"}, "request_id": "req_abc123"}
|
||||
|
||||
// 参数错误（HTTP 400）
|
||||
{"code": 400, "message": "用户名不能为空", "data": null, "request_id": "req_def456"}
|
||||
|
||||
// 业务错误（HTTP 422）
|
||||
{"code": 10001, "message": "余额不足", "data": null, "request_id": "req_ghi789"}
|
||||
```
|
||||
|
||||
### data 字段格式规范
|
||||
|
||||
| 接口类型 | data 结构 | 示例 |
|
||||
|----------|----------|------|
|
||||
| 分页列表 | `{list, total, page, page_size}` | `{"list": [...], "total": 100, "page": 1, "page_size": 20}` |
|
||||
| 不分页列表 | `{list}` | `{"list": [...]}` |
|
||||
| 创建资源 | `{id}` | `{"id": 42}` |
|
||||
| 资源详情 | 直接返回对象 | `{"id": 1, "name": "张三", ...}` |
|
||||
| 更新/删除 | `null` | `null` |
|
||||
|
||||
**规则**：
|
||||
- 列表数据的数组字段名统一用 `list`，禁止使用 `data`、`items`、`records` 等其他名称
|
||||
- 分页列表必须返回 `total`（总条数）和 `page`（当前页码），可选返回 `page_size`
|
||||
- 创建操作只返回新资源的 `id`，不返回完整对象
|
||||
- 更新/删除操作返回 `null`，前端通过 HTTP 200 + `code: 0` 判断成功
|
||||
- 如果 list 内部可以为空，但是不能有 null 出现
|
||||
|
||||
### HTTP 状态码映射规则
|
||||
|
||||
| 业务场景 | HTTP 状态码 | code 值 | 说明 |
|
||||
|----------|------------|---------|------|
|
||||
| 成功 | 200 | `0` | 请求处理成功 |
|
||||
| 参数校验失败 | 400 | `400` | 请求体格式错误、必填字段缺失、值不合法 |
|
||||
| 未认证 | 401 | `401` | Token 缺失、过期、无效 |
|
||||
| 无权限 | 403 | `403` | 已认证但无权访问该资源 |
|
||||
| 资源不存在 | 404 | `404` | 查询的对象不存在 |
|
||||
| 请求频率超限 | 429 | `429` | 触发限流 |
|
||||
| 业务规则错误 | 422 | `>= 10000` | 业务逻辑不满足，使用自定义错误码（见 `consts.go`） |
|
||||
| 服务器内部错误 | 500 | `500` | 未预期的异常 |
|
||||
|
||||
### 业务错误码定义（>= 10000）
|
||||
|
||||
业务错误码定义在 `internal/consts/consts.go` 中，每个错误码有对应的中文消息常量。新增业务错误时必须同时在 `consts.go` 中添加 `Code` 和 `Msg` 常量。
|
||||
|
||||
| 错误码 | 常量名 | 默认消息 |
|
||||
|--------|--------|---------|
|
||||
| 10001 | `CodeInsufficientBalance` | 余额不足 |
|
||||
| 10002 | `CodeQuotaExceeded` | 额度已用完 |
|
||||
| 10003 | `CodeChannelUnavailable` | 没有可用的渠道 |
|
||||
| ... | 更多见 `consts.go` | ... |
|
||||
|
||||
## 大模型代理接口格式（`/v1/*`、`/v1beta/*`、`/suno/*`）
|
||||
|
||||
### 已注册的代理端点
|
||||
|
||||
| 方法 | 路径 | 功能 | 请求格式 | 流式支持 |
|
||||
|------|------|------|---------|---------|
|
||||
| POST | `/v1/chat/completions` | Chat Completions | OpenAI | SSE |
|
||||
| POST | `/v1/completions` | Text Completions | OpenAI | SSE |
|
||||
| POST | `/v1/embeddings` | 文本向量 | OpenAI | 否 |
|
||||
| POST | `/v1/images/generations` | 图像生成 | OpenAI | 否 |
|
||||
| POST | `/v1/images/edits` | 图像编辑 | OpenAI | 否 |
|
||||
| POST | `/v1/messages` | Claude Messages | Claude | SSE |
|
||||
| POST | `/v1/responses` | OpenAI Responses | OpenAI | SSE |
|
||||
| POST | `/v1/audio/speech` | 语音合成 | OpenAI | 否 |
|
||||
| POST | `/v1/audio/transcriptions` | 语音转文字 | OpenAI | 否 |
|
||||
| POST | `/v1/audio/translations` | 语音翻译 | OpenAI | 否 |
|
||||
| POST | `/v1/rerank` | 重排序 | OpenAI | 否 |
|
||||
| POST | `/v1/moderations` | 内容审核 | OpenAI | 否 |
|
||||
| GET | `/v1/models` | 模型列表 | — | 否 |
|
||||
| GET | `/v1/models/{model_id}` | 模型详情 | — | 否 |
|
||||
| GET | `/v1/realtime` | 实时对话（WebSocket） | OpenAI | WebSocket |
|
||||
| POST | `/v1/video/generations` | 视频生成（异步任务） | 自定义 | 否 |
|
||||
| GET | `/v1/video/generations/{task_id}` | 视频生成任务查询 | — | 否 |
|
||||
| GET | `/v1beta/models` | Gemini 模型列表 | Gemini | 否 |
|
||||
| GET | `/v1beta/models/{model}` | Gemini 模型详情 | Gemini | 否 |
|
||||
| POST | `/v1beta/models/{model}` | Gemini 内容生成 | Gemini | SSE |
|
||||
| POST | `/suno/submit/{action}` | Suno 音乐生成提交 | 自定义 | 否 |
|
||||
| POST | `/suno/fetch` | Suno 批量查询 | 自定义 | 否 |
|
||||
| GET | `/suno/fetch/{task_id}` | Suno 任务查询 | — | 否 |
|
||||
|
||||
### OpenAI 格式端点响应
|
||||
|
||||
**非流式响应**直接透传上游 JSON，典型结构：
|
||||
|
||||
```json
|
||||
// Chat Completions 响应
|
||||
{
|
||||
"id": "chatcmpl-abc123",
|
||||
"object": "chat.completion",
|
||||
"created": 1677652288,
|
||||
"model": "gpt-4o",
|
||||
"choices": [
|
||||
{
|
||||
"index": 0,
|
||||
"message": {"role": "assistant", "content": "Hello!"},
|
||||
"finish_reason": "stop"
|
||||
}
|
||||
],
|
||||
"usage": {
|
||||
"prompt_tokens": 9,
|
||||
"completion_tokens": 12,
|
||||
"total_tokens": 21
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
// Embeddings 响应
|
||||
{
|
||||
"object": "list",
|
||||
"data": [
|
||||
{"object": "embedding", "embedding": [0.1, 0.2, ...], "index": 0}
|
||||
],
|
||||
"model": "text-embedding-3-small",
|
||||
"usage": {"prompt_tokens": 5, "total_tokens": 5}
|
||||
}
|
||||
```
|
||||
|
||||
**流式响应**使用 SSE（Server-Sent Events），`Content-Type: text/event-stream`：
|
||||
|
||||
```
|
||||
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
|
||||
|
||||
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
|
||||
|
||||
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":9,"completion_tokens":12,"total_tokens":21}}
|
||||
|
||||
data: [DONE]
|
||||
```
|
||||
|
||||
**OpenAI 格式错误响应**：
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"type": "invalid_request_error",
|
||||
"message": "余额不足，请联系管理员充值",
|
||||
"param": null,
|
||||
"code": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**错误类型映射**：
|
||||
|
||||
| 平台错误场景 | error.type | HTTP 状态码 |
|
||||
|-------------|-----------|------------|
|
||||
| 认证失败（API Key 无效） | `authentication_error` | 401 |
|
||||
| 权限不足（Key 无权访问模型） | `permission_error` | 403 |
|
||||
| 余额不足 / 额度耗尽 | `insufficient_quota` | 402 |
|
||||
| 模型不存在 / 参数错误 | `invalid_request_error` | 400 |
|
||||
| 请求频率超限 | `rate_limit_error` | 429 |
|
||||
| 没有可用渠道 | `server_error` | 503 |
|
||||
| 上游供应商错误 | 原样透传上游错误类型 | 上游状态码 |
|
||||
| 平台内部错误 | `internal_error` | 500 |
|
||||
|
||||
### Claude 格式端点响应（`/messages`）
|
||||
|
||||
**非流式响应**：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "msg_abc123",
|
||||
"type": "message",
|
||||
"role": "assistant",
|
||||
"content": [{"type": "text", "text": "Hello!"}],
|
||||
"model": "claude-sonnet-4-20250514",
|
||||
"stop_reason": "end_turn",
|
||||
"usage": {
|
||||
"input_tokens": 25,
|
||||
"output_tokens": 10
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**流式响应（SSE）**：
|
||||
|
||||
```
|
||||
event: message_start
|
||||
data: {"type":"message_start","message":{"id":"msg_abc123","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-20250514","usage":{"input_tokens":25,"output_tokens":0}}}
|
||||
|
||||
event: content_block_delta
|
||||
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello!"}}
|
||||
|
||||
event: message_delta
|
||||
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":10}}
|
||||
|
||||
event: message_stop
|
||||
data: {"type":"message_stop"}
|
||||
```
|
||||
|
||||
**Claude 格式错误响应**：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "error",
|
||||
"error": {
|
||||
"type": "authentication_error",
|
||||
"message": "余额不足，请联系管理员充值"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Gemini 格式端点响应（`/v1beta/models/*`）
|
||||
|
||||
使用 Google Gemini API 原生格式透传，错误格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": 400,
|
||||
"message": "请求参数错误",
|
||||
"status": "INVALID_ARGUMENT"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 错误处理实现规范
|
||||
|
||||
- `WriteRelayError(w, err)` — 写入 OpenAI 格式错误，用于 `/v1/chat/completions`、`/v1/embeddings` 等 OpenAI 格式端点
|
||||
- `WriteClaudeRelayError(w, err)` — 写入 Claude 格式错误，用于 `/v1/messages` 端点
|
||||
- 平台级错误（余额不足、渠道不可用、频率限制）转换为供应商原生格式的错误类型，消息使用中文
|
||||
- 上游供应商错误原样透传，不做二次包装
|
||||
- 限流错误额外设置 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 响应头
|
||||
|
||||
## 中间件配置差异
|
||||
|
||||
| 中间件 | 管理接口 | 代理接口 |
|
||||
|--------|---------|---------|
|
||||
| AdminAuth / TenantAuth（JWT） | 使用 | 不使用 |
|
||||
| ApiKeyAuth（Bearer Token） | 不使用 | 使用 |
|
||||
| MiddlewareHandlerResponse（统一响应） | 使用 | 不使用 |
|
||||
| ErrorHandler | 使用（支付回调） | 不使用 |
|
||||
| MaintenanceMode（维护模式） | 使用（租户） | 使用 |
|
||||
| ContentFilter（内容过滤） | 不使用 | 使用 |
|
||||
| OperationLog（操作日志） | 使用（管理后台） | 不使用 |
|
||||
| OpenPlatformAuth（HMAC-SHA256） | 仅开放平台 | 不使用 |
|
||||
| RBAC（权限校验） | 使用 | 不使用 |
|
||||
| Idempotency（幂等性） | 按需使用 | 不使用 |
|
||||
| RequestID 注入 | 使用 | 使用 |
|
||||
@@ -0,0 +1,257 @@
|
||||
# GoFrame 框架使用规范
|
||||
|
||||
本文档记录项目中 GoFrame v2 的使用规范、正确模式和已修复的框架使用错误。开发时按需查阅，发现新的框架使用 bug 修复后同步更新本文档。
|
||||
|
||||
> **提示**：遇到不确定的 GoFrame 用法时，可使用 `/goframe-v2` skill 查询框架最新规范和最佳实践。
|
||||
|
||||
## 时间处理
|
||||
|
||||
### 规则
|
||||
|
||||
- **ORM 写入**：使用 `gtime.Now()`，与 GoFrame ORM 的时间类型自然兼容
|
||||
- **纯计算/计时**：使用标准库 `time.Now()`（如 `time.Since(start)` 计算耗时、`time.Now().Unix()` 生成时间戳）
|
||||
- **time → gtime 转换**：使用 `gtime.NewFromTime(t)` 包装后再写入 ORM
|
||||
|
||||
### 正确示例
|
||||
|
||||
```go
|
||||
// ORM 写入场景 — 用 gtime
|
||||
dao.XxxTable.Ctx(ctx).Data(g.Map{
|
||||
"updated_at": gtime.Now(),
|
||||
}).Update()
|
||||
|
||||
// 耗时计算 — 用标准 time
|
||||
start := time.Now()
|
||||
doSomething()
|
||||
elapsed := time.Since(start)
|
||||
|
||||
// time.Time 转 gtime 写入 ORM
|
||||
nextRetry := time.Now().Add(delay)
|
||||
dao.XxxTable.Ctx(ctx).Data(g.Map{
|
||||
"next_retry_at": gtime.NewFromTime(nextRetry),
|
||||
}).Update()
|
||||
```
|
||||
|
||||
### 常见错误
|
||||
|
||||
- 在 ORM `.Data()` 中直接传 `time.Now()` — 应使用 `gtime.Now()`
|
||||
- 在 `time.Since()` 中使用 `gtime.Now()` — 应使用 `time.Now()`
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 规则
|
||||
|
||||
- 业务错误使用 `gerror.NewCode(gcode.New(code, msg, nil), msg)` 创建预定义错误常量
|
||||
- 预定义错误常量放在 `internal/consts/consts.go`
|
||||
- 包装底层错误时使用 `gerror.Wrapf(err, "context message")`
|
||||
- 临时业务错误使用 `gerror.Newf("中文提示 %s", param)`
|
||||
- Controller 层不处理错误，直接 `return nil, err` 交给中间件统一处理
|
||||
|
||||
### 错误码分级
|
||||
|
||||
| 码段 | 用途 | 示例 |
|
||||
|------|------|------|
|
||||
| 400-499 | 标准 HTTP 客户端错误 | 401 未认证、403 无权限、404 不存在 |
|
||||
| 500 | 服务器内部错误 | 未预期的异常 |
|
||||
| >= 10000 | 业务规则错误（HTTP 422） | 10001 余额不足、10002 额度用完 |
|
||||
|
||||
### 正确示例
|
||||
|
||||
```go
|
||||
// consts.go — 预定义业务错误
|
||||
var ErrInsufficientBalance = gerror.NewCode(
|
||||
gcode.New(CodeInsufficientBalance, MsgInsufficientBalance, nil),
|
||||
MsgInsufficientBalance,
|
||||
)
|
||||
|
||||
// logic 层 — 返回预定义错误
|
||||
if balance < amount {
|
||||
return nil, consts.ErrInsufficientBalance
|
||||
}
|
||||
|
||||
// logic 层 — 包装底层错误
|
||||
result, err := dao.XxxTable.Ctx(ctx).Insert(data)
|
||||
if err != nil {
|
||||
return nil, gerror.Wrapf(err, "insert xxx")
|
||||
}
|
||||
|
||||
// logic 层 — 临时业务错误
|
||||
return nil, gerror.Newf("兑换码状态为%s", redemption.Status)
|
||||
```
|
||||
|
||||
### 错误安全规则
|
||||
|
||||
`internal/response` 包自动执行错误脱敏：
|
||||
- 业务错误（>= 10000）和 HTTP 4xx：原始消息透传给客户端
|
||||
- 其他错误（数据库、网络等）：替换为 `"服务器内部错误"`，原始错误记日志
|
||||
- 禁止在错误消息中暴露 SQL、堆栈、内部路径等技术细节
|
||||
|
||||
## 日志记录
|
||||
|
||||
### 规则
|
||||
|
||||
- 统一使用 `g.Log()` 全局日志，不要创建自定义 Logger 实例
|
||||
- **必须传 ctx**：`g.Log().Errorf(ctx, "message: %v", err)`，确保日志携带 request_id
|
||||
- 日志级别：`Error`（需要修复的异常）、`Warning`（降级处理、已脱敏的错误）、`Info`（关键业务事件）
|
||||
- 后台 goroutine 中如果没有请求 ctx，使用 `context.TODO()`
|
||||
|
||||
### 正确示例
|
||||
|
||||
```go
|
||||
g.Log().Errorf(ctx, "update task %d to failed: %v", taskID, err)
|
||||
g.Log().Warningf(ctx, "webhook: config %d auto-disabled after %d failures", configID, count)
|
||||
g.Log().Infof(ctx, "API key %d disabled, cache invalidation for prefix %s", keyID, prefix)
|
||||
```
|
||||
|
||||
### 常见错误
|
||||
|
||||
- `g.Log().Error("message")` — 缺少 ctx，日志中不会有 request_id
|
||||
- 在可恢复的业务场景使用 Error 级别 — 应使用 Warning
|
||||
|
||||
## ORM 操作
|
||||
|
||||
### DAO 模式（优先）
|
||||
|
||||
```go
|
||||
// 查询
|
||||
var user entity.TntUsers
|
||||
err := dao.TntUsers.Ctx(ctx).Where("id", id).Where("tenant_id", tenantID).Scan(&user)
|
||||
|
||||
// 插入（使用 DO 结构体）
|
||||
id, err := dao.ChnChannels.Ctx(ctx).InsertAndGetId(do.ChnChannels{
|
||||
Name: req.Name,
|
||||
Provider: req.Provider,
|
||||
})
|
||||
|
||||
// 更新（使用 DO 结构体）
|
||||
_, err := dao.TntUsers.Ctx(ctx).Where("id", id).Data(do.TntUsers{
|
||||
Status: "disabled",
|
||||
}).Update()
|
||||
|
||||
// 删除
|
||||
_, err := dao.ApiKeys.Ctx(ctx).Where("id", id).Where("tenant_id", tenantID).Delete()
|
||||
|
||||
// 分页
|
||||
m := dao.TntUsers.Ctx(ctx).Where("tenant_id", tenantID)
|
||||
total, _ := m.Count()
|
||||
var list []entity.TntUsers
|
||||
err := m.Page(page, pageSize).OrderDesc("id").Scan(&list)
|
||||
```
|
||||
|
||||
### 原生 SQL（仅用于复杂查询和批量操作）
|
||||
|
||||
```go
|
||||
// 聚合查询、分析报表等无法用 ORM 表达的场景
|
||||
result, err := g.DB().Ctx(ctx).Raw(`
|
||||
SELECT date_trunc('hour', created_at) AS hour, count(*)
|
||||
FROM aud_request_logs WHERE ...
|
||||
`, args...).All()
|
||||
|
||||
// 原子更新（如余额操作）
|
||||
_, err = g.DB().Exec(ctx,
|
||||
`UPDATE bil_wallets SET balance = balance - $1 WHERE id = $2 AND balance >= $1`,
|
||||
amount, walletID,
|
||||
)
|
||||
```
|
||||
|
||||
### 事务
|
||||
|
||||
```go
|
||||
err := g.DB().Transaction(ctx, func(ctx context.Context, tx gdb.TX) error {
|
||||
// tx.Model() 替代 dao.Xxx.Ctx()，确保操作在同一事务内
|
||||
_, err := tx.Model("tnt_tenants").Ctx(ctx).Data(do.TntTenants{...}).Insert()
|
||||
if err != nil {
|
||||
return err // 自动回滚
|
||||
}
|
||||
_, err = tx.Model("tnt_users").Ctx(ctx).Data(do.TntUsers{...}).Insert()
|
||||
return err
|
||||
})
|
||||
```
|
||||
|
||||
### g.Map vs DO 结构体
|
||||
|
||||
- **新增/全量更新**：优先使用 `do.XxxTable{}` 结构体，类型安全
|
||||
- **部分更新**：可使用 `g.Map{"field": value}`，灵活但需注意字段名拼写
|
||||
- **混用场景**：changelog 等直接操作表名的场景可用 `g.DB().Model("table").Data(g.Map{...})`
|
||||
|
||||
## 配置读取
|
||||
|
||||
```go
|
||||
// 使用 g.Cfg() 读取 manifest/config/ 下的配置
|
||||
secret := g.Cfg().MustGet(ctx, "jwt.secret").String()
|
||||
maxSessions := g.Cfg().MustGet(ctx, "jwt.adminMaxSessions").Int()
|
||||
hexKey := g.Cfg().MustGet(ctx, "crypto.encryptionKey").String()
|
||||
```
|
||||
|
||||
## 参数校验
|
||||
|
||||
API 结构体使用 `v` tag 声明校验规则，GoFrame 自动执行校验：
|
||||
|
||||
```go
|
||||
type CreateAdminUserReq struct {
|
||||
g.Meta `path:"/admin-users" method:"post" tags:"管理员" summary:"创建管理员"`
|
||||
Username string `json:"username" v:"required|length:3,50#请输入用户名|用户名长度为3-50位"`
|
||||
Password string `json:"password" v:"required|length:8,64#请输入密码|密码长度为8-64位"`
|
||||
Status string `json:"status" v:"required|in:active,disabled#请选择状态|状态值无效"`
|
||||
}
|
||||
```
|
||||
|
||||
- `#` 后面是自定义中文错误消息，多个规则的消息用 `|` 分隔
|
||||
- 校验失败自动返回 400 错误，无需在 logic 层重复校验
|
||||
|
||||
## 类型转换
|
||||
|
||||
使用 `gconv` 包进行安全类型转换：
|
||||
|
||||
```go
|
||||
name := gconv.String(record["name"])
|
||||
ids := gconv.Int64s(record["user_ids"])
|
||||
rate := gconv.Float64(record["threshold"])
|
||||
methods := gconv.Strings(record["notification_methods"])
|
||||
```
|
||||
|
||||
## 缓存
|
||||
|
||||
项目使用 `gcache` 作为 L1 内存缓存，封装在 `internal/logic/common/cache.go`：
|
||||
|
||||
```go
|
||||
// 通过 common 包的缓存封装使用，不要直接调用 gcache
|
||||
common.CacheSet(ctx, "key", value, ttl)
|
||||
val, err := common.CacheGet(ctx, "key")
|
||||
common.CacheRemove(ctx, "key")
|
||||
```
|
||||
|
||||
## Context 传递
|
||||
|
||||
```go
|
||||
// 从 Context 读取请求级变量（中间件注入）
|
||||
requestID := r.GetCtxVar("RequestId").String()
|
||||
scope := r.GetCtxVar("ApiKeyScope").String()
|
||||
|
||||
// 获取当前请求对象
|
||||
r := g.RequestFromCtx(ctx)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 已修复的框架使用错误记录
|
||||
|
||||
> 每次修复 GoFrame 框架使用相关的 bug 后，在此处记录修复内容、原因和正确做法，防止同类问题再次出现。
|
||||
|
||||
### 2026-04-16：GoFrame gcode 非标准码用作 HTTP 状态码导致 panic
|
||||
|
||||
**问题**：`response.Error()` 中直接将 `gerror.Code().Code()` 作为 HTTP 状态码传给 `WriteHeader()`，但 GoFrame 内置的 `gcode`（如 `CodeNotModified=68`）不是合法 HTTP 状态码，导致 `WriteHeader` panic。
|
||||
|
||||
**修复**：在 `response.go` 中增加范围检查，非 100-599 的 code 回退为 500。
|
||||
|
||||
### 2026-04-16：MiddlewareHandlerResponse 未过滤文件下载响应
|
||||
|
||||
**问题**：导出 CSV/Excel 时，控制器直接写入 `r.Response.Writer`，但中间件仍然追加 `{"code":0,...}` JSON 到响应体末尾，导致文件损坏。
|
||||
|
||||
**修复**：在 `handler_response.go` 中检查 `Content-Type`，匹配 `text/csv`、`application/vnd.openxmlformats` 等下载类型时跳过 JSON 包装。
|
||||
|
||||
### 2026-04-16：isSystemError 日志污染
|
||||
|
||||
**问题**：所有错误（包括 400 参数校验、401 认证失败等正常业务流）都以 Warning 级别记录日志，大量无意义日志淹没真正的异常。
|
||||
|
||||
**修复**：增加 `isSystemError()` 函数，4xx 和 >= 10000 的业务错误不记日志，只有 5xx 和未知错误才记录。
|
||||
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,992 @@
|
||||
# FLUX 及其他图像生成 API 文档
|
||||
|
||||
## 概述
|
||||
|
||||
本文档涵盖 FLUX 模型系列及通过第三方平台（Together AI、Replicate、Fireworks AI、Black Forest Labs）提供的图像生成 API。
|
||||
|
||||
---
|
||||
|
||||
## 一、Black Forest Labs（BFL）— FLUX 模型官方 API
|
||||
|
||||
### 概述
|
||||
|
||||
Black Forest Labs（BFL）是 FLUX 模型的创建者，由 Stable Diffusion 原始团队成员创立。FLUX 系列是目前开源图像生成领域最先进的模型之一。
|
||||
|
||||
- **官网**：https://blackforestlabs.ai
|
||||
- **API 文档**：https://docs.bfl.ml
|
||||
- **API Base URL**：`https://api.bfl.ml`
|
||||
- **认证方式**：Bearer Token（API Key）
|
||||
- **协议格式**：REST + JSON
|
||||
|
||||
### 可用模型
|
||||
|
||||
| 模型 ID | 说明 | 特点 |
|
||||
|---------|------|------|
|
||||
| `flux-pro-1.1` | FLUX.1.1 Pro | 高质量，6 步生成 |
|
||||
| `flux-pro-1.0` | FLUX.1 Pro | 旗舰级质量 |
|
||||
| `flux-dev-1.0` | FLUX.1 Dev | 开发者版本，可自部署 |
|
||||
| `flux-schnell-1.0` | FLUX.1 Schnell | 快速版，4 步生成，Apache 2.0 开源 |
|
||||
| `flux-kontext-1.0` | FLUX.1 Kontext | 图像编辑（inpainting/outpainting） |
|
||||
| `flux-canny-1.0` | FLUX.1 Canny | Canny 边缘引导生成 |
|
||||
| `flux-depth-1.0` | FLUX.1 Depth | 深度图引导生成 |
|
||||
| `flux-fill-1.0` | FLUX.1 Fill | 局部重绘/填充 |
|
||||
|
||||
### 认证
|
||||
|
||||
```
|
||||
X-Key: sk-xxxxxxxxxxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
在请求头中使用 `X-Key` 字段传递 API Key。
|
||||
|
||||
### API 端点
|
||||
|
||||
#### 1. 文生图（Text to Image）
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
POST https://api.bfl.ml/v1/flux-pro-1.1
|
||||
```
|
||||
|
||||
**Headers**
|
||||
|
||||
| Header | 值 | 必填 |
|
||||
|--------|---|------|
|
||||
| `Content-Type` | `application/json` | 是 |
|
||||
| `X-Key` | `sk-xxx` | 是 |
|
||||
|
||||
**请求体**
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": "A beautiful sunset over a calm ocean with vibrant colors",
|
||||
"width": 1024,
|
||||
"height": 1024,
|
||||
"steps": 25,
|
||||
"guidance": 3.5,
|
||||
"seed": 42,
|
||||
"safety_tolerance": 2,
|
||||
"output_format": "jpeg",
|
||||
"output_quality": 80
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| `prompt` | string | 是 | — | 正向提示词 |
|
||||
| `width` | integer | 否 | `1024` | 图像宽度。推荐值：512 ~ 1536，必须是 16 的倍数 |
|
||||
| `height` | integer | 否 | `1024` | 图像高度。推荐值：512 ~ 1536，必须是 16 的倍数 |
|
||||
| `steps` | integer | 否 | `25` | 推理步数。范围：1 ~ 50（Schnell 推荐 4） |
|
||||
| `guidance` | float | 否 | `3.0` | CFG 引导尺度。范围：1.0 ~ 20.0 |
|
||||
| `seed` | integer | 否 | 随机 | 随机种子。范围：0 ~ 4294967295 |
|
||||
| `safety_tolerance` | integer | 否 | `2` | 安全过滤级别。范围：1 ~ 6，1=最严格，6=最宽松 |
|
||||
| `output_format` | string | 否 | `"jpeg"` | 输出格式。可选值：`"jpeg"`, `"png"` |
|
||||
| `output_quality` | integer | 否 | `80` | JPEG 输出质量。范围：1 ~ 100（仅 JPEG 有效） |
|
||||
|
||||
#### 2. 图生图（Image to Image）
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
POST https://api.bfl.ml/v1/flux-pro-1.1-ultra
|
||||
```
|
||||
|
||||
**请求体**
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": "Transform into a watercolor painting",
|
||||
"image": "base64_encoded_image_data",
|
||||
"image_prompt": "watercolor style artwork",
|
||||
"strength": 0.7,
|
||||
"width": 1024,
|
||||
"height": 1024,
|
||||
"steps": 25,
|
||||
"guidance": 3.5,
|
||||
"seed": 42,
|
||||
"output_format": "png"
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| `prompt` | string | 是 | — | 提示词 |
|
||||
| `image` | string | 是 | — | Base64 编码的输入图像 |
|
||||
| `image_prompt` | string | 否 | `""` | 图像提示词（额外引导） |
|
||||
| `strength` | float | 否 | `0.5` | 图像变化强度。范围：0.0 ~ 1.0 |
|
||||
|
||||
#### 3. 局部重绘（Inpainting / Fill）
|
||||
|
||||
```
|
||||
POST https://api.bfl.ml/v1/flux-fill-1.0
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": "A beautiful garden with flowers",
|
||||
"image": "base64_encoded_image",
|
||||
"mask": "base64_encoded_mask",
|
||||
"width": 1024,
|
||||
"height": 1024,
|
||||
"steps": 25,
|
||||
"guidance": 3.5,
|
||||
"seed": 42
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `prompt` | string | 是 | 重绘区域描述 |
|
||||
| `image` | string | 是 | Base64 编码的原始图像 |
|
||||
| `mask` | string | 是 | Base64 编码的遮罩图像（白色区域为重绘区域） |
|
||||
|
||||
#### 4. Canny 边缘引导生成
|
||||
|
||||
```
|
||||
POST https://api.bfl.ml/v1/flux-canny-1.0
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": "A futuristic city skyline",
|
||||
"control_image": "base64_encoded_control_image",
|
||||
"guidance": 3.5,
|
||||
"steps": 25,
|
||||
"seed": 42
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. 深度图引导生成
|
||||
|
||||
```
|
||||
POST https://api.bfl.ml/v1/flux-depth-1.0
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": "A cozy living room",
|
||||
"control_image": "base64_encoded_depth_map",
|
||||
"guidance": 3.5,
|
||||
"steps": 25,
|
||||
"seed": 42
|
||||
}
|
||||
```
|
||||
|
||||
### 异步响应
|
||||
|
||||
BFL API 默认返回异步任务：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "abc123-def456",
|
||||
"status": "Pending",
|
||||
"result": null
|
||||
}
|
||||
```
|
||||
|
||||
**轮询结果**
|
||||
|
||||
```
|
||||
GET https://api.bfl.ml/v1/get_result?id=abc123-def456
|
||||
```
|
||||
|
||||
**Headers**
|
||||
|
||||
```
|
||||
X-Key: sk-xxx
|
||||
```
|
||||
|
||||
**完成响应**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "abc123-def456",
|
||||
"status": "Ready",
|
||||
"result": {
|
||||
"sample": "https://delivery.bfl.ml/xxx/image.jpeg",
|
||||
"prompt": "A beautiful sunset..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | string | 任务 ID |
|
||||
| `status` | string | 任务状态：`"Pending"`、`"Ready"`、`"Failed"` |
|
||||
| `result.sample` | string | 生成图像的 URL |
|
||||
| `result.prompt` | string | 使用的提示词 |
|
||||
|
||||
### 错误响应
|
||||
|
||||
```json
|
||||
{
|
||||
"status_code": 400,
|
||||
"errors": [
|
||||
{
|
||||
"message": "Invalid request: prompt is required"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 定价（参考）
|
||||
|
||||
| 模型 | 每张价格 | 说明 |
|
||||
|------|---------|------|
|
||||
| FLUX.1.1 Pro | ~$0.04 | 高质量 |
|
||||
| FLUX.1 Pro | ~$0.05 | 旗舰级 |
|
||||
| FLUX.1 Schnell | ~$0.003 | 快速/低成本 |
|
||||
|
||||
---
|
||||
|
||||
## 二、Together AI — FLUX/SDXL 图像生成
|
||||
|
||||
### 概述
|
||||
|
||||
Together AI 提供多种开源图像模型的托管推理服务，包括 FLUX 系列、Stable Diffusion XL 等。API 兼容 OpenAI Images 格式。
|
||||
|
||||
- **官网**：https://together.ai
|
||||
- **API 文档**：https://docs.together.ai
|
||||
- **API Base URL**：`https://api.together.xyz`
|
||||
- **认证方式**：Bearer Token
|
||||
- **协议格式**：兼容 OpenAI Images API
|
||||
|
||||
### 认证
|
||||
|
||||
```
|
||||
Authorization: Bearer {TOGETHER_API_KEY}
|
||||
```
|
||||
|
||||
### 可用图像模型
|
||||
|
||||
| 模型 ID | 说明 | 每步价格 | 质量 |
|
||||
|---------|------|---------|------|
|
||||
| `black-forest-labs/FLUX.1-schnell` | FLUX.1 Schnell（免费） | $0.00 | 快速 |
|
||||
| `black-forest-labs/FLUX.1-schnell-Free` | FLUX.1 Schnell 免费版 | $0.00 | 快速（限速） |
|
||||
| `black-forest-labs/FLUX.1.1-pro` | FLUX.1.1 Pro | 按量计费 | 高质量 |
|
||||
| `black-forest-labs/FLUX.1-pro` | FLUX.1 Pro | 按量计费 | 旗舰级 |
|
||||
| `stabilityai/stable-diffusion-xl-base-1.0` | SDXL 1.0 Base | 按量计费 | 中等质量 |
|
||||
|
||||
### API 端点
|
||||
|
||||
#### 图像生成
|
||||
|
||||
```
|
||||
POST https://api.together.xyz/v1/images/generations
|
||||
```
|
||||
|
||||
**请求体**
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "black-forest-labs/FLUX.1-schnell",
|
||||
"prompt": "A cat sitting on a windowsill looking at the moon",
|
||||
"n": 1,
|
||||
"size": "1024x1024",
|
||||
"steps": 4,
|
||||
"seed": 42,
|
||||
"response_format": "b64_json",
|
||||
"guidance_scale": 7.5
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| `model` | string | 是 | — | 模型 ID（见上方模型列表） |
|
||||
| `prompt` | string | 是 | — | 提示词 |
|
||||
| `n` | integer | 否 | `1` | 生成图像数量（最大 8） |
|
||||
| `size` | string | 否 | `"1024x1024"` | 图像尺寸。支持：`"256x256"`, `"512x512"`, `"1024x1024"`, `"1024x768"`, `"768x1024"`, `"1792x1024"`, `"1024x1792"` |
|
||||
| `steps` | integer | 否 | `20` | 推理步数。FLUX Schnell 推荐 4 |
|
||||
| `seed` | integer | 否 | 随机 | 随机种子 |
|
||||
| `response_format` | string | 否 | `"url"` | 响应格式。可选值：`"url"`, `"b64_json"` |
|
||||
| `guidance_scale` | float | 否 | `7.5` | CFG 引导尺度 |
|
||||
| `negative_prompt` | string | 否 | `""` | 反向提示词（部分模型支持） |
|
||||
| `width` | integer | 否 | 1024 | 图像宽度（可替代 size） |
|
||||
| `height` | integer | 否 | 1024 | 图像高度（可替代 size） |
|
||||
|
||||
**响应**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "gen-abc123",
|
||||
"object": "list",
|
||||
"created": 1677652288,
|
||||
"data": [
|
||||
{
|
||||
"url": "https://api.together.xyz/images/abc123.png",
|
||||
"b64_json": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
或（`response_format: "b64_json"`）：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "gen-abc123",
|
||||
"object": "list",
|
||||
"created": 1677652288,
|
||||
"data": [
|
||||
{
|
||||
"url": null,
|
||||
"b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**示例请求（cURL）**
|
||||
|
||||
```bash
|
||||
curl -X POST https://api.together.xyz/v1/images/generations \
|
||||
-H "Authorization: Bearer $TOGETHER_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "black-forest-labs/FLUX.1-schnell",
|
||||
"prompt": "A serene Japanese garden with cherry blossoms",
|
||||
"n": 1,
|
||||
"size": "1024x1024",
|
||||
"steps": 4,
|
||||
"response_format": "url"
|
||||
}'
|
||||
```
|
||||
|
||||
**示例请求（Python）**
|
||||
|
||||
```python
|
||||
from openai import OpenAI
|
||||
|
||||
client = OpenAI(
|
||||
api_key="your_together_api_key",
|
||||
base_url="https://api.together.xyz/v1"
|
||||
)
|
||||
|
||||
response = client.images.generate(
|
||||
model="black-forest-labs/FLUX.1-schnell",
|
||||
prompt="A serene Japanese garden with cherry blossoms",
|
||||
n=1,
|
||||
size="1024x1024",
|
||||
response_format="url"
|
||||
)
|
||||
|
||||
print(response.data[0].url)
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
|
||||
与 OpenAI 格式一致：
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"type": "invalid_request_error",
|
||||
"message": "Invalid model ID",
|
||||
"param": "model",
|
||||
"code": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 定价
|
||||
|
||||
| 模型 | 计费方式 |
|
||||
|------|---------|
|
||||
| FLUX.1 Schnell Free | 免费（有限速率） |
|
||||
| FLUX.1 Schnell | $0.002/张 |
|
||||
| FLUX.1.1 Pro | ~$0.03/张 |
|
||||
| FLUX.1 Pro | ~$0.04/张 |
|
||||
| SDXL 1.0 | ~$0.002/张 |
|
||||
|
||||
---
|
||||
|
||||
## 三、Replicate — 通用模型推理平台
|
||||
|
||||
### 概述
|
||||
|
||||
Replicate 提供云端模型推理服务，支持数千种模型（图像、视频、音频、文本）。图像生成是其核心功能之一，支持 FLUX、SDXL、Kandinsky、Playground 等多种模型。
|
||||
|
||||
- **官网**：https://replicate.com
|
||||
- **API 文档**：https://replicate.com/docs
|
||||
- **API Base URL**：`https://api.replicate.com`
|
||||
- **认证方式**：Bearer Token
|
||||
- **协议格式**：REST + JSON
|
||||
|
||||
### 认证
|
||||
|
||||
```
|
||||
Authorization: Bearer r8_xxxxxxxxxxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
在 https://replicate.com/account/api-tokens 获取 API Token。
|
||||
|
||||
### API 端点
|
||||
|
||||
#### 1. 创建预测（同步）
|
||||
|
||||
```
|
||||
POST https://api.replicate.com/v1/predictions
|
||||
```
|
||||
|
||||
**Headers**
|
||||
|
||||
| Header | 值 | 必填 |
|
||||
|--------|---|------|
|
||||
| `Authorization` | `Bearer r8_xxx` | 是 |
|
||||
| `Content-Type` | `application/json` | 是 |
|
||||
| `Prefer` | `wait` | 否 | 设置为 `wait` 表示同步等待结果（最长 60s） |
|
||||
|
||||
**请求体**
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "ac732df83cea7fff18b947a8b9a204a33cd3f2f1e5e6b1e5f5f5f5f5f5f5f5f5",
|
||||
"input": {
|
||||
"prompt": "A beautiful sunset over mountains",
|
||||
"width": 1024,
|
||||
"height": 1024,
|
||||
"num_outputs": 1,
|
||||
"guidance_scale": 7.5,
|
||||
"num_inference_steps": 28,
|
||||
"seed": 42
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `version` | string | 否 | 模型版本 ID（与 `model` 二选一） |
|
||||
| `model` | string | 否 | 模型标识（如 `"black-forest-labs/flux-schnell"`） |
|
||||
| `input` | object | 是 | 模型输入参数（因模型而异） |
|
||||
| `webhook` | string | 否 | 完成/失败时的回调 URL |
|
||||
| `webhook_events_filter` | array | 否 | 触发回调的事件：`["start", "output", "logs", "completed"]` |
|
||||
| `Cancel-After` | string | 否 | 超时时间（ISO 8601 duration，如 `"PT60S"`） |
|
||||
|
||||
#### 2. 创建预测（使用模型最新版本）
|
||||
|
||||
```
|
||||
POST https://api.replicate.com/v1/models/{owner}/{model}/predictions
|
||||
```
|
||||
|
||||
**请求体**
|
||||
|
||||
```json
|
||||
{
|
||||
"input": {
|
||||
"prompt": "A cat wearing a hat",
|
||||
"width": 1024,
|
||||
"height": 768,
|
||||
"num_inference_steps": 28,
|
||||
"guidance_scale": 3.5,
|
||||
"seed": 42
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 获取预测结果
|
||||
|
||||
```
|
||||
GET https://api.replicate.com/v1/predictions/{prediction_id}
|
||||
```
|
||||
|
||||
#### 4. 取消预测
|
||||
|
||||
```
|
||||
POST https://api.replicate.com/v1/predictions/{prediction_id}/cancel
|
||||
```
|
||||
|
||||
#### 5. 列出预测
|
||||
|
||||
```
|
||||
GET https://api.replicate.com/v1/predictions
|
||||
```
|
||||
|
||||
### 预测响应
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "abc123-def456-ghi789",
|
||||
"model": "black-forest-labs/flux-schnell",
|
||||
"version": "ac732df83cea...",
|
||||
"input": {
|
||||
"prompt": "A beautiful sunset"
|
||||
},
|
||||
"output": [
|
||||
"https://replicate.delivery/xxx/image1.png"
|
||||
],
|
||||
"status": "succeeded",
|
||||
"created_at": "2024-01-15T10:30:00.000Z",
|
||||
"started_at": "2024-01-15T10:30:01.000Z",
|
||||
"completed_at": "2024-01-15T10:30:15.000Z",
|
||||
"logs": "Using seed: 42\nGenerating...",
|
||||
"error": null,
|
||||
"metrics": {
|
||||
"predict_time": 14.5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | string | 预测唯一 ID |
|
||||
| `model` | string | 模型标识 |
|
||||
| `version` | string | 模型版本 ID |
|
||||
| `input` | object | 输入参数 |
|
||||
| `output` | array | 输出结果（通常是图像 URL 数组） |
|
||||
| `status` | string | 状态：`"starting"`, `"processing"`, `"succeeded"`, `"failed"`, `"canceled"` |
|
||||
| `created_at` | string | 创建时间（ISO 8601） |
|
||||
| `started_at` | string | 开始处理时间 |
|
||||
| `completed_at` | string | 完成时间 |
|
||||
| `logs` | string | 执行日志 |
|
||||
| `error` | string | 错误信息（失败时） |
|
||||
| `metrics` | object | 性能指标 |
|
||||
|
||||
### 状态流转
|
||||
|
||||
```
|
||||
starting → processing → succeeded
|
||||
→ failed
|
||||
→ canceled（手动取消）
|
||||
```
|
||||
|
||||
### Webhook 回调
|
||||
|
||||
当预测完成时，Replicate 向指定 URL 发送 POST 请求：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "abc123",
|
||||
"event": "completed",
|
||||
"status": "succeeded",
|
||||
"output": ["https://replicate.delivery/xxx/image.png"],
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
### 常用图像模型及输入参数
|
||||
|
||||
#### FLUX.1 Schnell
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "black-forest-labs/flux-schnell",
|
||||
"input": {
|
||||
"prompt": "description of the image",
|
||||
"num_outputs": 1,
|
||||
"aspect_ratio": "1:1",
|
||||
"output_format": "webp",
|
||||
"output_quality": 80,
|
||||
"seed": 42
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| `prompt` | string | — | 提示词 |
|
||||
| `num_outputs` | integer | 1 | 输出图像数量（1 ~ 4） |
|
||||
| `aspect_ratio` | string | `"1:1"` | 宽高比：`"1:1"`, `"16:9"`, `"9:16"`, `"4:3"`, `"3:4"`, `"3:2"`, `"2:3"` |
|
||||
| `output_format` | string | `"webp"` | 输出格式：`"webp"`, `"jpg"`, `"png"` |
|
||||
| `output_quality` | integer | 80 | 输出质量（1 ~ 100） |
|
||||
| `seed` | integer | 随机 | 随机种子 |
|
||||
|
||||
#### FLUX.1 Pro
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "black-forest-labs/flux-pro",
|
||||
"input": {
|
||||
"prompt": "description",
|
||||
"width": 1024,
|
||||
"height": 1024,
|
||||
"steps": 28,
|
||||
"guidance": 3.5,
|
||||
"interval": 0.5,
|
||||
"seed": 42
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| `prompt` | string | — | 提示词 |
|
||||
| `width` | integer | 1024 | 图像宽度 |
|
||||
| `height` | integer | 1024 | 图像高度 |
|
||||
| `steps` | integer | 28 | 推理步数 |
|
||||
| `guidance` | float | 3.5 | CFG 引导尺度 |
|
||||
| `interval` | float | 0.5 | 引导间隔 |
|
||||
| `seed` | integer | 随机 | 随机种子 |
|
||||
|
||||
#### SDXL
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "stability-ai/sdxl",
|
||||
"input": {
|
||||
"prompt": "description",
|
||||
"negative_prompt": "blurry, bad quality",
|
||||
"width": 1024,
|
||||
"height": 1024,
|
||||
"num_inference_steps": 30,
|
||||
"guidance_scale": 7.5,
|
||||
"scheduler": "K_EULER",
|
||||
"seed": 42,
|
||||
"num_outputs": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
|
||||
```json
|
||||
{
|
||||
"status": 422,
|
||||
"detail": "Input validation failed: prompt is required"
|
||||
}
|
||||
```
|
||||
|
||||
### 定价
|
||||
|
||||
Replicate 按推理时间计费，不同模型价格不同：
|
||||
|
||||
| 模型 | 每秒价格 | 典型生成时间 | 每张价格 |
|
||||
|------|---------|-------------|---------|
|
||||
| FLUX.1 Schnell | ~$0.0003/s | ~2s | ~$0.003 |
|
||||
| FLUX.1 Pro | ~$0.0003/s | ~10s | ~$0.03 |
|
||||
| SDXL | ~$0.0003/s | ~5s | ~$0.01 |
|
||||
|
||||
### Python SDK
|
||||
|
||||
```python
|
||||
import replicate
|
||||
|
||||
# 方式1：使用模型标识
|
||||
output = replicate.run(
|
||||
"black-forest-labs/flux-schnell",
|
||||
input={
|
||||
"prompt": "A cat in a garden",
|
||||
"aspect_ratio": "16:9",
|
||||
"output_format": "png"
|
||||
}
|
||||
)
|
||||
|
||||
# output 是图像 URL 列表
|
||||
print(output[0]) # https://replicate.delivery/xxx/image.png
|
||||
|
||||
# 方式2：异步预测
|
||||
prediction = replicate.predictions.create(
|
||||
model="black-forest-labs/flux-schnell",
|
||||
input={"prompt": "A cat in a garden"},
|
||||
webhook="https://your-app.com/webhook",
|
||||
webhook_events_filter=["completed"]
|
||||
)
|
||||
|
||||
# 轮询
|
||||
prediction.reload()
|
||||
while prediction.status not in ["succeeded", "failed", "canceled"]:
|
||||
time.sleep(1)
|
||||
prediction.reload()
|
||||
```
|
||||
|
||||
### Go HTTP 调用示例
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
"time"
|
||||
)
|
||||
|
||||
type PredictionRequest struct {
|
||||
Model string `json:"model"`
|
||||
Input map[string]interface{} `json:"input"`
|
||||
}
|
||||
|
||||
type Prediction struct {
|
||||
ID string `json:"id"`
|
||||
Status string `json:"status"`
|
||||
Output []string `json:"output"`
|
||||
Error string `json:"error"`
|
||||
}
|
||||
|
||||
func createPrediction(apiKey string, req PredictionRequest) (*Prediction, error) {
|
||||
body, _ := json.Marshal(req)
|
||||
httpReq, _ := http.NewRequest("POST",
|
||||
"https://api.replicate.com/v1/predictions",
|
||||
bytes.NewReader(body))
|
||||
httpReq.Header.Set("Authorization", "Bearer "+apiKey)
|
||||
httpReq.Header.Set("Content-Type", "application/json")
|
||||
httpReq.Header.Set("Prefer", "wait")
|
||||
|
||||
resp, err := http.DefaultClient.Do(httpReq)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
|
||||
var pred Prediction
|
||||
json.NewDecoder(resp.Body).Decode(&pred)
|
||||
return &pred, nil
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、Fireworks AI — 图像生成
|
||||
|
||||
### 概述
|
||||
|
||||
Fireworks AI 提供快速推理服务，支持 FLUX、Stable Diffusion 等多种图像生成模型，以低延迟和高吞吐著称。
|
||||
|
||||
- **官网**：https://fireworks.ai
|
||||
- **API 文档**：https://docs.fireworks.ai
|
||||
- **API Base URL**：`https://api.fireworks.ai`
|
||||
- **认证方式**：Bearer Token
|
||||
- **协议格式**：兼容 OpenAI Images API
|
||||
|
||||
### 认证
|
||||
|
||||
```
|
||||
Authorization: Bearer {FIREWORKS_API_KEY}
|
||||
```
|
||||
|
||||
### 可用模型
|
||||
|
||||
| 模型 ID | 说明 |
|
||||
|---------|------|
|
||||
| `stable-diffusion-xl-1024-v1-0` | SDXL 1.0 |
|
||||
| `FLUX.1-schnell` | FLUX Schnell 快速版 |
|
||||
| `FLUX.1-dev` | FLUX Dev 开发者版 |
|
||||
|
||||
### API 端点
|
||||
|
||||
#### 图像生成
|
||||
|
||||
```
|
||||
POST https://api.fireworks.ai/v1/images/generations
|
||||
```
|
||||
|
||||
**请求体**
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "FLUX.1-schnell",
|
||||
"prompt": "A dragon flying over a medieval castle",
|
||||
"n": 1,
|
||||
"size": "1024x1024",
|
||||
"cfg_scale": 7.5,
|
||||
"steps": 4,
|
||||
"seed": 42,
|
||||
"sampler": "DDIM"
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| `model` | string | 是 | — | 模型 ID |
|
||||
| `prompt` | string | 是 | — | 提示词 |
|
||||
| `n` | integer | 否 | `1` | 生成数量 |
|
||||
| `size` | string | 否 | `"1024x1024"` | 图像尺寸 |
|
||||
| `cfg_scale` | float | 否 | `7.0` | CFG 引导尺度 |
|
||||
| `steps` | integer | 否 | `20` | 推理步数 |
|
||||
| `seed` | integer | 否 | 随机 | 随机种子 |
|
||||
| `sampler` | string | 否 | 自动 | 采样器类型 |
|
||||
| `negative_prompt` | string | 否 | `""` | 反向提示词 |
|
||||
|
||||
**响应**
|
||||
|
||||
兼容 OpenAI Images API 格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"created": 1677652288,
|
||||
"data": [
|
||||
{
|
||||
"url": "https://fireworks-api-images.s3.amazonaws.com/xxx/image.png"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 示例请求
|
||||
|
||||
```bash
|
||||
curl -X POST https://api.fireworks.ai/v1/images/generations \
|
||||
-H "Authorization: Bearer $FIREWORKS_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "FLUX.1-schnell",
|
||||
"prompt": "A majestic phoenix rising from flames",
|
||||
"n": 1,
|
||||
"size": "1024x1024",
|
||||
"steps": 4
|
||||
}'
|
||||
```
|
||||
|
||||
### Python 示例（兼容 OpenAI SDK）
|
||||
|
||||
```python
|
||||
from openai import OpenAI
|
||||
|
||||
client = OpenAI(
|
||||
api_key="your_fireworks_api_key",
|
||||
base_url="https://api.fireworks.ai/v1"
|
||||
)
|
||||
|
||||
response = client.images.generate(
|
||||
model="FLUX.1-schnell",
|
||||
prompt="A majestic phoenix rising from flames",
|
||||
n=1,
|
||||
size="1024x1024"
|
||||
)
|
||||
|
||||
print(response.data[0].url)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、各平台对比总结
|
||||
|
||||
### 功能对比
|
||||
|
||||
| 特性 | BFL 官方 | Together AI | Replicate | Fireworks AI |
|
||||
|------|---------|-------------|-----------|-------------|
|
||||
| 认证方式 | `X-Key` Header | Bearer Token | Bearer Token | Bearer Token |
|
||||
| 请求格式 | JSON | JSON（OpenAI 兼容） | JSON | JSON（OpenAI 兼容） |
|
||||
| 响应格式 | 异步 + URL | OpenAI 格式 | 异步 + URL | OpenAI 格式 |
|
||||
| OpenAI SDK 兼容 | 否 | 是 | 否 | 是 |
|
||||
| 文生图 | ✓ | ✓ | ✓ | ✓ |
|
||||
| 图生图 | ✓ | 部分支持 | ✓ | 部分支持 |
|
||||
| 局部重绘 | ✓（Fill 模型） | 部分支持 | ✓ | 部分支持 |
|
||||
| Canny/Depth 引导 | ✓ | — | ✓ | — |
|
||||
| Webhook | — | — | ✓ | — |
|
||||
| 免费额度 | 无 | Schnell 免费 | 无 | 无 |
|
||||
| FLUX 模型 | 全系列 | Schnell + Pro | 全系列 | Schnell + Dev |
|
||||
| SDXL | — | ✓ | ✓ | ✓ |
|
||||
|
||||
### 价格对比（每张 1024x1024 图像，参考价格）
|
||||
|
||||
| 模型 | BFL 官方 | Together AI | Replicate | Fireworks AI |
|
||||
|------|---------|-------------|-----------|-------------|
|
||||
| FLUX.1 Schnell | ~$0.003 | 免费 / $0.002 | ~$0.003 | ~$0.002 |
|
||||
| FLUX.1 Pro | ~$0.05 | ~$0.04 | ~$0.03 | — |
|
||||
| FLUX.1.1 Pro | ~$0.04 | ~$0.03 | ~$0.035 | — |
|
||||
| SDXL | — | ~$0.002 | ~$0.01 | ~$0.002 |
|
||||
|
||||
### 延迟对比
|
||||
|
||||
| 模型 | BFL 官方 | Together AI | Replicate | Fireworks AI |
|
||||
|------|---------|-------------|-----------|-------------|
|
||||
| FLUX Schnell | ~2s | ~2s | ~3s | ~1s |
|
||||
| FLUX Pro | ~10s | ~10s | ~12s | — |
|
||||
| SDXL | — | ~5s | ~6s | ~3s |
|
||||
|
||||
---
|
||||
|
||||
## 六、team-api 适配器实现参考
|
||||
|
||||
### 端点映射
|
||||
|
||||
对于 OpenAI 兼容的供应商（Together AI、Fireworks AI），可以直接透传 `/v1/images/generations` 请求，只需替换 base URL 和 API Key。
|
||||
|
||||
| team-api 入口 | Together AI | Fireworks AI | Replicate |
|
||||
|--------------|-------------|-------------|-----------|
|
||||
| `POST /v1/images/generations` | `POST /v1/images/generations` | `POST /v1/images/generations` | `POST /v1/predictions` |
|
||||
| `POST /v1/images/edits` | 不支持 | 不支持 | `POST /v1/predictions` |
|
||||
| `POST /v1/images/variations` | 不支持 | 不支持 | `POST /v1/predictions` |
|
||||
|
||||
### 请求转换（OpenAI 兼容供应商）
|
||||
|
||||
Together AI 和 Fireworks AI 的请求格式与 OpenAI 基本一致，适配器只需：
|
||||
|
||||
1. 替换 `base_url`（`api.openai.com` → `api.together.xyz` / `api.fireworks.ai`）
|
||||
2. 替换 `model` 字段（`dall-e-3` → `black-forest-labs/FLUX.1-schnell`）
|
||||
3. 透传其余参数
|
||||
|
||||
### 请求转换（Replicate）
|
||||
|
||||
Replicate 的请求格式与 OpenAI 差异较大，需要专用适配器：
|
||||
|
||||
```go
|
||||
// OpenAI Images 请求 → Replicate 预测请求
|
||||
func ConvertToReplicateRequest(openaiReq *OpenAIImageRequest) *ReplicateRequest {
|
||||
input := map[string]interface{}{
|
||||
"prompt": openaiReq.Prompt,
|
||||
"aspect_ratio": sizeToAspectRatio(openaiReq.Size),
|
||||
"output_format": "png",
|
||||
"num_outputs": openaiReq.N,
|
||||
}
|
||||
if openaiReq.Seed > 0 {
|
||||
input["seed"] = openaiReq.Seed
|
||||
}
|
||||
|
||||
return &ReplicateRequest{
|
||||
Model: mapModelToReplicate(openaiReq.Model),
|
||||
Input: input,
|
||||
}
|
||||
}
|
||||
|
||||
// Replicate 响应 → OpenAI Images 响应
|
||||
func ConvertFromReplicateResponse(resp *ReplicatePrediction) *OpenAIImageResponse {
|
||||
data := make([]ImageData, len(resp.Output))
|
||||
for i, url := range resp.Output {
|
||||
data[i] = ImageData{URL: url}
|
||||
}
|
||||
return &OpenAIImageResponse{
|
||||
Created: time.Now().Unix(),
|
||||
Data: data,
|
||||
}
|
||||
}
|
||||
|
||||
// 尺寸映射
|
||||
func sizeToAspectRatio(size string) string {
|
||||
switch size {
|
||||
case "1024x1024": return "1:1"
|
||||
case "1792x1024": return "16:9"
|
||||
case "1024x1792": return "9:16"
|
||||
case "1536x1024": return "3:2"
|
||||
case "1024x1536": return "2:3"
|
||||
default: return "1:1"
|
||||
}
|
||||
}
|
||||
|
||||
// 模型映射
|
||||
func mapModelToReplicate(model string) string {
|
||||
switch model {
|
||||
case "flux-schnell": return "black-forest-labs/flux-schnell"
|
||||
case "flux-pro": return "black-forest-labs/flux-pro"
|
||||
case "sdxl": return "stability-ai/sdxl"
|
||||
default: return model
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Replicate 异步轮询
|
||||
|
||||
```go
|
||||
func PollReplicatePrediction(apiKey, predictionID string, timeout time.Duration) (*ReplicatePrediction, error) {
|
||||
deadline := time.Now().Add(timeout)
|
||||
for time.Now().Before(deadline) {
|
||||
pred, err := GetPrediction(apiKey, predictionID)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
switch pred.Status {
|
||||
case "succeeded":
|
||||
return pred, nil
|
||||
case "failed":
|
||||
return nil, fmt.Errorf("prediction failed: %s", pred.Error)
|
||||
case "canceled":
|
||||
return nil, fmt.Errorf("prediction was canceled")
|
||||
}
|
||||
time.Sleep(1 * time.Second)
|
||||
}
|
||||
return nil, fmt.Errorf("prediction timed out after %v", timeout)
|
||||
}
|
||||
```
|
||||
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,292 @@
|
||||
# Models
|
||||
|
||||
The models endpoint provides a way for you to programmatically list the available models, and retrieve extended metadata such as supported functionality and context window sizing. Read more in [the Models guide](https://ai.google.dev/gemini-api/docs/models/gemini).
|
||||
|
||||
## Method: models.get
|
||||
|
||||
- [Endpoint](https://ai.google.dev/api/models#body.HTTP_TEMPLATE)
|
||||
- [Path parameters](https://ai.google.dev/api/models#body.PATH_PARAMETERS)
|
||||
- [Request body](https://ai.google.dev/api/models#body.request_body)
|
||||
- [Response body](https://ai.google.dev/api/models#body.response_body)
|
||||
- [Authorization scopes](https://ai.google.dev/api/models#body.aspect)
|
||||
- [Example request](https://ai.google.dev/api/models#body.codeSnippets)
|
||||
- [Get](https://ai.google.dev/api/models#body.codeSnippets.group)
|
||||
|
||||
Gets information about a specific `Model` such as its version number, token limits, [parameters](https://ai.google.dev/gemini-api/docs/models/generative-models#model-parameters) and other metadata. Refer to the [Gemini models guide](https://ai.google.dev/gemini-api/docs/models/gemini) for detailed model information.
|
||||
|
||||
### Endpoint
|
||||
|
||||
get `https://generativelanguage.googleapis.com/v1beta/{name=models/*}`
|
||||
|
||||
### Path parameters
|
||||
|
||||
`name` `string` Required. The resource name of the model.
|
||||
|
||||
This name should match a model name returned by the `models.list` method.
|
||||
|
||||
Format: `models/{model}` It takes the form `models/{model}`.
|
||||
|
||||
### Request body
|
||||
|
||||
The request body must be empty.
|
||||
|
||||
### Example request
|
||||
|
||||
### Python
|
||||
|
||||
from google import genai
|
||||
|
||||
client = genai.Client()
|
||||
model_info = client.models.get(model="gemini-2.0-flash")
|
||||
print(model_info)https://github.com/google-gemini/api-examples/blob/4ce9033e1d2f857db3f728d78399e3d7ded8ef05/python/models.py#L41-L45
|
||||
|
||||
### Go
|
||||
|
||||
ctx := context.Background()
|
||||
client, err := genai.NewClient(ctx, &genai.ClientConfig{
|
||||
APIKey: os.Getenv("GEMINI_API_KEY"),
|
||||
Backend: genai.BackendGeminiAPI,
|
||||
})
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
modelInfo, err := client.Models.Get(ctx, "gemini-2.0-flash", nil)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
fmt.Println(modelInfo)https://github.com/google-gemini/api-examples/blob/4ce9033e1d2f857db3f728d78399e3d7ded8ef05/go/models.go#L55-L69
|
||||
|
||||
### Shell
|
||||
|
||||
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash?key=$GEMINI_API_KEYhttps://github.com/google-gemini/deprecated-generative-ai-python/blob/7a7cc5474ddaa0255a4410e05361028a24400abd/samples/rest/models.sh#L9-L10
|
||||
|
||||
### Response body
|
||||
|
||||
If successful, the response body contains an instance of `https://ai.google.dev/api/models#Model`.
|
||||
|
||||
## Method: models.list
|
||||
|
||||
- [Endpoint](https://ai.google.dev/api/models#body.HTTP_TEMPLATE)
|
||||
- [Query parameters](https://ai.google.dev/api/models#body.QUERY_PARAMETERS)
|
||||
- [Request body](https://ai.google.dev/api/models#body.request_body)
|
||||
- [Response body](https://ai.google.dev/api/models#body.response_body)
|
||||
- [JSON representation](https://ai.google.dev/api/models#body.ListModelsResponse.SCHEMA_REPRESENTATION)
|
||||
- [Authorization scopes](https://ai.google.dev/api/models#body.aspect)
|
||||
- [Example request](https://ai.google.dev/api/models#body.codeSnippets)
|
||||
- [List](https://ai.google.dev/api/models#body.codeSnippets.group)
|
||||
|
||||
Lists the [`Model`s](https://ai.google.dev/gemini-api/docs/models/gemini) available through the Gemini API.
|
||||
|
||||
### Endpoint
|
||||
|
||||
get `https://generativelanguage.googleapis.com/v1beta/models`
|
||||
|
||||
### Query parameters
|
||||
|
||||
`pageSize` `integer` The maximum number of `Models` to return (per page).
|
||||
|
||||
If unspecified, 50 models will be returned per page. This method returns at most 1000 models per page, even if you pass a larger pageSize.
|
||||
`pageToken` `string` A page token, received from a previous `models.list` call.
|
||||
|
||||
Provide the `pageToken` returned by one request as an argument to the next request to retrieve the next page.
|
||||
|
||||
When paginating, all other parameters provided to `models.list` must match the call that provided the page token.
|
||||
|
||||
### Request body
|
||||
|
||||
The request body must be empty.
|
||||
|
||||
### Example request
|
||||
|
||||
### Python
|
||||
|
||||
from google import genai
|
||||
|
||||
client = genai.Client()
|
||||
|
||||
print("List of models that support generateContent:\n")
|
||||
for m in client.models.list():
|
||||
for action in m.supported_actions:
|
||||
if action == "generateContent":
|
||||
print(m.name)
|
||||
|
||||
print("List of models that support embedContent:\n")
|
||||
for m in client.models.list():
|
||||
for action in m.supported_actions:
|
||||
if action == "embedContent":
|
||||
print(m.name)https://github.com/google-gemini/api-examples/blob/4ce9033e1d2f857db3f728d78399e3d7ded8ef05/python/models.py#L22-L36
|
||||
|
||||
### Go
|
||||
|
||||
ctx := context.Background()
|
||||
client, err := genai.NewClient(ctx, &genai.ClientConfig{
|
||||
APIKey: os.Getenv("GEMINI_API_KEY"),
|
||||
Backend: genai.BackendGeminiAPI,
|
||||
})
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
|
||||
// Retrieve the list of models.
|
||||
models, err := client.Models.List(ctx, &genai.ListModelsConfig{})
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
fmt.Println("List of models that support generateContent:")
|
||||
for _, m := range models.Items {
|
||||
for _, action := range m.SupportedActions {
|
||||
if action == "generateContent" {
|
||||
fmt.Println(m.Name)
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fmt.Println("\nList of models that support embedContent:")
|
||||
for _, m := range models.Items {
|
||||
for _, action := range m.SupportedActions {
|
||||
if action == "embedContent" {
|
||||
fmt.Println(m.Name)
|
||||
break
|
||||
}
|
||||
}
|
||||
}https://github.com/google-gemini/api-examples/blob/4ce9033e1d2f857db3f728d78399e3d7ded8ef05/go/models.go#L14-L48
|
||||
|
||||
### Shell
|
||||
|
||||
curl https://generativelanguage.googleapis.com/v1beta/models?key=$GEMINI_API_KEYhttps://github.com/google-gemini/deprecated-generative-ai-python/blob/7a7cc5474ddaa0255a4410e05361028a24400abd/samples/rest/models.sh#L4-L5
|
||||
|
||||
### Response body
|
||||
|
||||
Response from `ListModel` containing a paginated list of Models.
|
||||
|
||||
If successful, the response body contains data with the following structure:
|
||||
Fields `models[]` ``object (`https://ai.google.dev/api/models#Model`)`` The returned Models.
|
||||
`nextPageToken` `string` A token, which can be sent as `pageToken` to retrieve the next page.
|
||||
|
||||
If this field is omitted, there are no more pages.
|
||||
|
||||
| JSON representation |
|
||||
|---|
|
||||
| ``` { "models": [ { object (`https://ai.google.dev/api/models#Model`) } ], "nextPageToken": string } ``` |
|
||||
|
||||
## REST Resource: models
|
||||
|
||||
- [Resource: Model](https://ai.google.dev/api/models#Model)
|
||||
- [JSON representation](https://ai.google.dev/api/models#Model.SCHEMA_REPRESENTATION)
|
||||
- [Methods](https://ai.google.dev/api/models#METHODS_SUMMARY)
|
||||
|
||||
## Resource: Model
|
||||
|
||||
Information about a Generative Language Model.
|
||||
Fields `name` `string` Required. The resource name of the `Model`. Refer to [Model variants](https://ai.google.dev/gemini-api/docs/models/gemini#model-variations) for all allowed values.
|
||||
|
||||
Format: `models/{model}` with a `{model}` naming convention of:
|
||||
|
||||
- "{baseModelId}-{version}"
|
||||
|
||||
Examples:
|
||||
|
||||
- `models/gemini-1.5-flash-001`
|
||||
`baseModelId` `string` Required. The name of the base model, pass this to the generation request.
|
||||
|
||||
Examples:
|
||||
|
||||
- `gemini-1.5-flash`
|
||||
`version` `string` Required. The version number of the model.
|
||||
|
||||
This represents the major version (`1.0` or `1.5`)
|
||||
`displayName` `string` The human-readable name of the model. E.g. "Gemini 1.5 Flash".
|
||||
|
||||
The name can be up to 128 characters long and can consist of any UTF-8 characters.
|
||||
`description` `string` A short description of the model.
|
||||
`inputTokenLimit` `integer` Maximum number of input tokens allowed for this model.
|
||||
`outputTokenLimit` `integer` Maximum number of output tokens available for this model.
|
||||
`supportedGenerationMethods[]` `string` The model's supported generation methods.
|
||||
|
||||
The corresponding API method names are defined as Pascal case strings, such as `generateMessage` and `generateContent`.
|
||||
`thinking` `boolean` Whether the model supports thinking.
|
||||
`temperature` `number` Controls the randomness of the output.
|
||||
|
||||
Values can range over `[0.0,maxTemperature]`, inclusive. A higher value will produce responses that are more varied, while a value closer to `0.0` will typically result in less surprising responses from the model. This value specifies default to be used by the backend while making the call to the model.
|
||||
`maxTemperature` `number` The maximum temperature this model can use.
|
||||
`topP` `number` For [Nucleus sampling](https://ai.google.dev/gemini-api/docs/prompting-strategies#top-p).
|
||||
|
||||
Nucleus sampling considers the smallest set of tokens whose probability sum is at least `topP`. This value specifies default to be used by the backend while making the call to the model.
|
||||
`topK` `integer` For Top-k sampling.
|
||||
|
||||
Top-k sampling considers the set of `topK` most probable tokens. This value specifies default to be used by the backend while making the call to the model. If empty, indicates the model doesn't use top-k sampling, and `topK` isn't allowed as a generation parameter.
|
||||
|
||||
| JSON representation |
|
||||
|---|
|
||||
| ``` { "name": string, "baseModelId": string, "version": string, "displayName": string, "description": string, "inputTokenLimit": integer, "outputTokenLimit": integer, "supportedGenerationMethods": [ string ], "thinking": boolean, "temperature": number, "maxTemperature": number, "topP": number, "topK": integer } ``` |
|
||||
|
||||
## Method: models.predict
|
||||
|
||||
- [Endpoint](https://ai.google.dev/api/models#body.HTTP_TEMPLATE)
|
||||
- [Path parameters](https://ai.google.dev/api/models#body.PATH_PARAMETERS)
|
||||
- [Request body](https://ai.google.dev/api/models#body.request_body)
|
||||
- [JSON representation](https://ai.google.dev/api/models#body.request_body.SCHEMA_REPRESENTATION)
|
||||
- [Response body](https://ai.google.dev/api/models#body.response_body)
|
||||
- [JSON representation](https://ai.google.dev/api/models#body.PredictResponse.SCHEMA_REPRESENTATION)
|
||||
- [Authorization scopes](https://ai.google.dev/api/models#body.aspect)
|
||||
|
||||
Performs a prediction request.
|
||||
|
||||
### Endpoint
|
||||
|
||||
post `https://generativelanguage.googleapis.com/v1beta/{model=models/*}:predict`
|
||||
|
||||
### Path parameters
|
||||
|
||||
`model` `string` Required. The name of the model for prediction. Format: `name=models/{model}`. It takes the form `models/{model}`.
|
||||
|
||||
### Request body
|
||||
|
||||
The request body contains data with the following structure:
|
||||
Fields `instances[]` ``value (`https://protobuf.dev/reference/protobuf/google.protobuf#value` format)`` Required. The instances that are the input to the prediction call.
|
||||
`parameters` ``value (`https://protobuf.dev/reference/protobuf/google.protobuf#value` format)`` Optional. The parameters that govern the prediction call.
|
||||
|
||||
### Response body
|
||||
|
||||
Response message for \[PredictionService.Predict\].
|
||||
|
||||
If successful, the response body contains data with the following structure:
|
||||
Fields `predictions[]` ``value (`https://protobuf.dev/reference/protobuf/google.protobuf#value` format)`` The outputs of the prediction call.
|
||||
|
||||
| JSON representation |
|
||||
|---|
|
||||
| ``` { "predictions": [ value ] } ``` |
|
||||
|
||||
## Method: models.predictLongRunning
|
||||
|
||||
- [Endpoint](https://ai.google.dev/api/models#body.HTTP_TEMPLATE)
|
||||
- [Path parameters](https://ai.google.dev/api/models#body.PATH_PARAMETERS)
|
||||
- [Request body](https://ai.google.dev/api/models#body.request_body)
|
||||
- [JSON representation](https://ai.google.dev/api/models#body.request_body.SCHEMA_REPRESENTATION)
|
||||
- [Response body](https://ai.google.dev/api/models#body.response_body)
|
||||
- [Authorization scopes](https://ai.google.dev/api/models#body.aspect)
|
||||
|
||||
Same as models.predict but returns an LRO.
|
||||
|
||||
### Endpoint
|
||||
|
||||
post `https://generativelanguage.googleapis.com/v1beta/{model=models/*}:predictLongRunning`
|
||||
|
||||
### Path parameters
|
||||
|
||||
`model` `string` Required. The name of the model for prediction. Format: `name=models/{model}`.
|
||||
|
||||
### Request body
|
||||
|
||||
The request body contains data with the following structure:
|
||||
Fields `instances[]` ``value (`https://protobuf.dev/reference/protobuf/google.protobuf#value` format)`` Required. The instances that are the input to the prediction call.
|
||||
`parameters` ``value (`https://protobuf.dev/reference/protobuf/google.protobuf#value` format)`` Optional. The parameters that govern the prediction call.
|
||||
|
||||
### Response body
|
||||
|
||||
If successful, the response body contains an instance of `https://ai.google.dev/api/batch-api#Operation`.
|
||||
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,637 @@
|
||||
# 图像生成 API 协议文档
|
||||
|
||||
> 基于 OpenAI Images API 官方文档 (https://platform.openai.com/docs/api-reference/images) 整理
|
||||
>
|
||||
> 本文档用于 team-api 协议转换模块的开发参考，涵盖图像生成（Generations）、图像编辑（Edits）、图像变体（Variations）三个端点的完整请求/响应规范，以及各供应商适配器的协议差异。
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
- [1. API 概览](#1-api-概览)
|
||||
- [2. 认证方式](#2-认证方式)
|
||||
- [3. 图像生成 (Create Image)](#3-图像生成-create-image)
|
||||
- [4. 图像编辑 (Edit Image)](#4-图像编辑-edit-image)
|
||||
- [5. 图像变体 (Create Image Variation)](#5-图像变体-create-image-variation)
|
||||
- [6. 响应格式](#6-响应格式)
|
||||
- [7. 流式响应 (GPT Image 模型)](#7-流式响应-gpt-image-模型)
|
||||
- [8. 各模型参数差异对比](#8-各模型参数差异对比)
|
||||
- [9. 错误格式](#9-错误格式)
|
||||
- [10. 供应商适配器协议差异](#10-供应商适配器协议差异)
|
||||
- [11. 协议转换注意事项](#11-协议转换注意事项)
|
||||
|
||||
---
|
||||
|
||||
## 1. API 概览
|
||||
|
||||
OpenAI 图像 API 提供三个端点，支持 DALL-E 系列和 GPT Image 系列模型：
|
||||
|
||||
| 端点 | 方法 | 路径 | 功能 | 支持模型 |
|
||||
|------|------|------|------|----------|
|
||||
| 图像生成 | POST | `/v1/images/generations` | 根据文本提示生成图像 | `dall-e-2`, `dall-e-3`, `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5` |
|
||||
| 图像编辑 | POST | `/v1/images/edits` | 编辑现有图像（支持多图） | `dall-e-2`, `gpt-image-1` |
|
||||
| 图像变体 | POST | `/v1/images/variations` | 基于现有图像生成变体 | `dall-e-2` |
|
||||
|
||||
### 基本请求示例（图像生成）
|
||||
|
||||
```bash
|
||||
curl https://api.openai.com/v1/images/generations \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer $OPENAI_API_KEY" \
|
||||
-d '{
|
||||
"model": "gpt-image-1",
|
||||
"prompt": "A cute baby sea otter",
|
||||
"n": 1,
|
||||
"size": "1024x1024"
|
||||
}'
|
||||
```
|
||||
|
||||
### 基本请求示例（图像编辑，multipart/form-data）
|
||||
|
||||
```bash
|
||||
curl https://api.openai.com/v1/images/edits \
|
||||
-H "Authorization: Bearer $OPENAI_API_KEY" \
|
||||
-F image="@otter.png" \
|
||||
-F prompt="A cute baby sea otter wearing a beret" \
|
||||
-F model="gpt-image-1"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 认证方式
|
||||
|
||||
请求头中携带 Bearer Token，与 Chat Completions API 相同：
|
||||
|
||||
```
|
||||
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
| 认证方式 | 说明 |
|
||||
|---------|------|
|
||||
| API Key | `Authorization: Bearer sk-xxx`，在平台 API Keys 页面创建 |
|
||||
| Organization（可选） | `OpenAI-Organization: org-xxx`，指定组织 |
|
||||
| Project（可选） | `OpenAI-Project: proj-xxx`，指定项目 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 图像生成 (Create Image)
|
||||
|
||||
**端点**：`POST /v1/images/generations`
|
||||
|
||||
**Content-Type**：`application/json`
|
||||
|
||||
### 3.1 完整参数表
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 适用模型 | 说明 |
|
||||
|--------|------|------|--------|----------|------|
|
||||
| `prompt` | string | **是** | — | 全部 | 图像描述文本。GPT Image 最长 32000 字符，dall-e-2 最长 1000 字符，dall-e-3 最长 4000 字符 |
|
||||
| `model` | string | **是** | `dall-e-2` | — | 模型 ID：`dall-e-2`、`dall-e-3`、`gpt-image-1`、`gpt-image-1-mini`、`gpt-image-1.5` |
|
||||
| `n` | integer | 否 | `1` | 全部 | 生成图像数量。dall-e-2/dall-e-3: 1；GPT Image: 1-10 |
|
||||
| `size` | string | 否 | `1024x1024` | 全部 | 图像尺寸，各模型支持值不同，详见下方 |
|
||||
| `quality` | string | 否 | `auto` | GPT Image; dall-e-3 | 图像质量。GPT Image: `auto`/`high`/`medium`/`low`；dall-e-3: `standard`/`hd` |
|
||||
| `response_format` | string | 否 | `url` | 全部 | 返回格式：`url` 或 `b64_json`。GPT Image 默认 `b64_json` |
|
||||
| `background` | string | 否 | `auto` | GPT Image | 背景透明度：`transparent`、`opaque`、`auto`。仅支持 PNG/WebP 输出格式 |
|
||||
| `output_format` | string | 否 | `png` | GPT Image | 输出图像格式：`png`、`jpeg`、`webp` |
|
||||
| `output_compression` | integer | 否 | — | GPT Image | 输出压缩率（0-100），仅 `jpeg` 和 `webp` 格式有效。100 = 无压缩 |
|
||||
| `partial_images` | integer | 否 | `0` | GPT Image | 流式中间图数量（0-3）。设为非 0 时自动启用流式模式 |
|
||||
| `stream` | boolean | 否 | `false` | GPT Image | 是否启用流式响应。也可通过 `partial_images > 0` 隐式启用 |
|
||||
| `style` | string | 否 | `vivid` | dall-e-3 | 图像风格：`vivid`（生动）或 `natural`（自然） |
|
||||
| `moderation` | string | 否 | `auto` | GPT Image | 内容审核严格度：`auto` 或 `low` |
|
||||
| `user` | string | 否 | — | 全部 | 终端用户标识符，用于监控滥用 |
|
||||
|
||||
### 3.2 各模型支持的尺寸
|
||||
|
||||
**dall-e-2**：
|
||||
|
||||
| 尺寸 |
|
||||
|------|
|
||||
| `256x256` |
|
||||
| `512x512` |
|
||||
| `1024x1024` |
|
||||
|
||||
**dall-e-3**：
|
||||
|
||||
| 尺寸 |
|
||||
|------|
|
||||
| `1024x1024` |
|
||||
| `1024x1792`（纵向） |
|
||||
| `1792x1024`（横向） |
|
||||
|
||||
**gpt-image-1 / gpt-image-1-mini / gpt-image-1.5**：
|
||||
|
||||
| 尺寸 |
|
||||
|------|
|
||||
| `1024x1024`（正方形） |
|
||||
| `1536x1024`（横向） |
|
||||
| `1024x1536`（纵向） |
|
||||
|
||||
### 3.3 请求示例
|
||||
|
||||
**DALL-E 3 高质量生成**：
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "dall-e-3",
|
||||
"prompt": "A white Siamese cat wearing a tiny top hat, digital art",
|
||||
"n": 1,
|
||||
"size": "1792x1024",
|
||||
"quality": "hd",
|
||||
"style": "vivid",
|
||||
"response_format": "url"
|
||||
}
|
||||
```
|
||||
|
||||
**GPT Image 透明背景 PNG**：
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "gpt-image-1",
|
||||
"prompt": "A red logo of a rocket ship, minimalist, clean design",
|
||||
"n": 1,
|
||||
"size": "1024x1024",
|
||||
"quality": "high",
|
||||
"background": "transparent",
|
||||
"output_format": "png"
|
||||
}
|
||||
```
|
||||
|
||||
**GPT Image 流式生成（含中间图）**：
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "gpt-image-1",
|
||||
"prompt": "A sunset over a mountain lake",
|
||||
"n": 1,
|
||||
"size": "1024x1024",
|
||||
"partial_images": 2
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 图像编辑 (Edit Image)
|
||||
|
||||
**端点**：`POST /v1/images/edits`
|
||||
|
||||
**Content-Type**：`multipart/form-data` 或 `application/json`（GPT Image 模型支持 JSON）
|
||||
|
||||
### 4.1 完整参数表
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 适用模型 | 说明 |
|
||||
|--------|------|------|--------|----------|------|
|
||||
| `image` | file / array | **是** | — | 全部 | 源图像文件。dall-e-2: 单个 PNG（正方形，<4MB）；GPT Image: 最多 16 张图（PNG/JPEG/WebP，每张 <20MB） |
|
||||
| `prompt` | string | **是** | — | 全部 | 编辑指令文本 |
|
||||
| `model` | string | 否 | `dall-e-2` | — | 模型 ID：`dall-e-2` 或 `gpt-image-1` |
|
||||
| `mask` | file | 否 | — | dall-e-2 | 遮罩图像（PNG，与源图同尺寸）。透明区域表示需要编辑的部分 |
|
||||
| `n` | integer | 否 | `1` | 全部 | 生成图像数量。dall-e-2: 1；GPT Image: 1-10 |
|
||||
| `size` | string | 否 | `1024x1024` | 全部 | 输出尺寸。dall-e-2: 256x256/512x512/1024x1024；GPT Image: 同生成端点 |
|
||||
| `response_format` | string | 否 | `url` | 全部 | 返回格式：`url` 或 `b64_json` |
|
||||
| `quality` | string | 否 | `auto` | GPT Image | 图像质量：`auto`/`high`/`medium`/`low` |
|
||||
| `background` | string | 否 | `auto` | GPT Image | 背景透明度：`transparent`/`opaque`/`auto` |
|
||||
| `output_format` | string | 否 | `png` | GPT Image | 输出格式：`png`/`jpeg`/`webp` |
|
||||
| `output_compression` | integer | 否 | — | GPT Image | 压缩率 0-100 |
|
||||
| `partial_images` | integer | 否 | `0` | GPT Image | 流式中间图数量 0-3 |
|
||||
| `stream` | boolean | 否 | `false` | GPT Image | 是否流式 |
|
||||
| `user` | string | 否 | — | 全部 | 终端用户标识 |
|
||||
|
||||
### 4.2 GPT Image 的 JSON 请求格式
|
||||
|
||||
GPT Image 模型支持以 JSON 传递图像 URL 或 base64 数据（而非 multipart/form-data）：
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "gpt-image-1",
|
||||
"prompt": "Add a red bow tie to the cat",
|
||||
"image": [
|
||||
{
|
||||
"type": "image_url",
|
||||
"url": "https://example.com/cat.png"
|
||||
}
|
||||
],
|
||||
"n": 1,
|
||||
"size": "1024x1024"
|
||||
}
|
||||
```
|
||||
|
||||
或使用 base64 内联：
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "gpt-image-1",
|
||||
"prompt": "Add a red bow tie to the cat",
|
||||
"image": [
|
||||
{
|
||||
"type": "image_url",
|
||||
"url": "data:image/png;base64,iVBORw0KGgo..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 DALL-E 2 的遮罩编辑
|
||||
|
||||
DALL-E 2 的编辑使用 mask 参数标记需要重新生成的区域。mask 必须满足：
|
||||
- 格式为 PNG
|
||||
- 尺寸与源图相同
|
||||
- 透明（alpha = 0）区域表示需要编辑的部分
|
||||
- 非透明区域保留原样
|
||||
|
||||
```bash
|
||||
curl https://api.openai.com/v1/images/edits \
|
||||
-H "Authorization: Bearer $OPENAI_API_KEY" \
|
||||
-F image="@original.png" \
|
||||
-F mask="@mask.png" \
|
||||
-F prompt="Replace the background with a beach" \
|
||||
-F model="dall-e-2"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 图像变体 (Create Image Variation)
|
||||
|
||||
**端点**：`POST /v1/images/variations`
|
||||
|
||||
**Content-Type**：`multipart/form-data`
|
||||
|
||||
**仅支持 `dall-e-2` 模型**。
|
||||
|
||||
### 5.1 完整参数表
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|--------|------|------|--------|------|
|
||||
| `image` | file | **是** | — | 源图像（PNG，正方形，<4MB） |
|
||||
| `model` | string | 否 | `dall-e-2` | 必须为 `dall-e-2` |
|
||||
| `n` | integer | 否 | `1` | 生成变体数量（1-10） |
|
||||
| `size` | string | 否 | `1024x1024` | 输出尺寸：`256x256`/`512x512`/`1024x1024` |
|
||||
| `response_format` | string | 否 | `url` | 返回格式：`url` 或 `b64_json` |
|
||||
| `user` | string | 否 | — | 终端用户标识 |
|
||||
|
||||
### 5.2 请求示例
|
||||
|
||||
```bash
|
||||
curl https://api.openai.com/v1/images/variations \
|
||||
-H "Authorization: Bearer $OPENAI_API_KEY" \
|
||||
-F image="@otter.png" \
|
||||
-F n=2 \
|
||||
-F size="1024x1024"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 响应格式
|
||||
|
||||
### 6.1 非流式响应（所有模型通用）
|
||||
|
||||
```json
|
||||
{
|
||||
"created": 1706734328,
|
||||
"data": [
|
||||
{
|
||||
"url": "https://oaidalleapiprodscus.blob.core.windows.net/private/...",
|
||||
"revised_prompt": "A white Siamese cat wearing a tiny top hat, rendered in digital art style with vibrant colors"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
或 base64 格式（`response_format: "b64_json"`）：
|
||||
|
||||
```json
|
||||
{
|
||||
"created": 1706734328,
|
||||
"data": [
|
||||
{
|
||||
"b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 GPT Image 增强响应
|
||||
|
||||
GPT Image 模型在响应中包含额外的元数据字段：
|
||||
|
||||
```json
|
||||
{
|
||||
"created": 1706734328,
|
||||
"data": [
|
||||
{
|
||||
"b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
|
||||
}
|
||||
],
|
||||
"background": "transparent",
|
||||
"output_format": "png",
|
||||
"size": "1024x1024",
|
||||
"quality": "high",
|
||||
"usage": {
|
||||
"total_tokens": 100,
|
||||
"input_tokens": 50,
|
||||
"output_tokens": 50,
|
||||
"input_tokens_details": {
|
||||
"text_tokens": 20,
|
||||
"image_tokens": 30
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6.3 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `created` | integer | 创建时间戳（Unix 时间） |
|
||||
| `data` | array | 图像数据数组 |
|
||||
| `data[].url` | string | 图像下载 URL（`response_format: "url"` 时返回，有效期 1 小时） |
|
||||
| `data[].b64_json` | string | 图像 Base64 编码（`response_format: "b64_json"` 时返回） |
|
||||
| `data[].revised_prompt` | string | 模型修改后的 prompt（dall-e-3 和 GPT Image 可能返回） |
|
||||
| `background` | string | 输出背景（GPT Image 专属） |
|
||||
| `output_format` | string | 输出格式（GPT Image 专属） |
|
||||
| `size` | string | 输出尺寸（GPT Image 专属） |
|
||||
| `quality` | string | 输出质量（GPT Image 专属） |
|
||||
| `usage` | object | Token 使用量（GPT Image 专属） |
|
||||
|
||||
### 6.4 Usage 字段说明（GPT Image）
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `usage.total_tokens` | integer | 总 token 数 |
|
||||
| `usage.input_tokens` | integer | 输入 token 数 |
|
||||
| `usage.output_tokens` | integer | 输出 token 数（图像 token） |
|
||||
| `usage.input_tokens_details.text_tokens` | integer | 文本输入 token 数 |
|
||||
| `usage.input_tokens_details.image_tokens` | integer | 图像输入 token 数（编辑场景） |
|
||||
|
||||
---
|
||||
|
||||
## 7. 流式响应 (GPT Image 模型)
|
||||
|
||||
仅 GPT Image 模型（`gpt-image-1`、`gpt-image-1-mini`、`gpt-image-1.5`）支持流式响应。通过设置 `stream: true` 或 `partial_images > 0` 启用。
|
||||
|
||||
**Content-Type**：`text/event-stream`
|
||||
|
||||
### 7.1 流式事件格式
|
||||
|
||||
流式响应通过 SSE 返回，每个事件包含一个 JSON 对象：
|
||||
|
||||
```
|
||||
data: {"type": "generation.partial", "data": [{"b64_json": "...", "index": 0}]}
|
||||
|
||||
data: {"type": "generation.partial", "data": [{"b64_json": "...", "index": 0}]}
|
||||
|
||||
data: {"type": "generation.completed", "data": [{"b64_json": "...", "index": 0}]}
|
||||
```
|
||||
|
||||
### 7.2 事件类型
|
||||
|
||||
| 事件类型 | 说明 |
|
||||
|---------|------|
|
||||
| `generation.partial` | 中间过程图，数量取决于 `partial_images` 参数 |
|
||||
| `generation.completed` | 最终完成的图像 |
|
||||
|
||||
### 7.3 流式请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "gpt-image-1",
|
||||
"prompt": "A beautiful mountain landscape at sunset",
|
||||
"n": 1,
|
||||
"size": "1024x1024",
|
||||
"partial_images": 2,
|
||||
"stream": true
|
||||
}
|
||||
```
|
||||
|
||||
### 7.4 流式响应完整示例
|
||||
|
||||
```
|
||||
data: {"type":"generation.partial","data":[{"b64_json":"iVBORw0KGgo...partial1","index":0}],"usage":{"total_tokens":0,"input_tokens":50,"output_tokens":0,"input_tokens_details":{"text_tokens":50,"image_tokens":0}}}
|
||||
|
||||
data: {"type":"generation.partial","data":[{"b64_json":"iVBORw0KGgo...partial2","index":0}],"usage":{"total_tokens":0,"input_tokens":50,"output_tokens":0,"input_tokens_details":{"text_tokens":50,"image_tokens":0}}}
|
||||
|
||||
data: {"type":"generation.completed","data":[{"b64_json":"iVBORw0KGgo...final","index":0}],"usage":{"total_tokens":100,"input_tokens":50,"output_tokens":50,"input_tokens_details":{"text_tokens":50,"image_tokens":0}}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 各模型参数差异对比
|
||||
|
||||
| 参数 | dall-e-2 | dall-e-3 | gpt-image-1 / mini / 1.5 |
|
||||
|------|----------|----------|--------------------------|
|
||||
| **生成端点** | 支持 | 支持 | 支持 |
|
||||
| **编辑端点** | 支持（mask） | 不支持 | 支持（多图，无 mask） |
|
||||
| **变体端点** | 支持 | 不支持 | 不支持 |
|
||||
| **prompt 最大长度** | 1000 字符 | 4000 字符 | 32000 字符 |
|
||||
| **n（生成数量）** | 1 | 1 | 1-10 |
|
||||
| **尺寸** | 256/512/1024 正方形 | 1024 正方形 + 横纵 1792 | 1024 正方形 + 1536 横纵 |
|
||||
| **quality** | 不支持 | `standard`/`hd` | `auto`/`high`/`medium`/`low` |
|
||||
| **style** | 不支持 | `vivid`/`natural` | 不支持 |
|
||||
| **background** | 不支持 | 不支持 | `transparent`/`opaque`/`auto` |
|
||||
| **output_format** | 不支持 | 不支持 | `png`/`jpeg`/`webp` |
|
||||
| **output_compression** | 不支持 | 不支持 | 0-100 |
|
||||
| **流式响应** | 不支持 | 不支持 | 支持（`partial_images`） |
|
||||
| **moderation** | 不支持 | 不支持 | `auto`/`low` |
|
||||
| **response_format 默认值** | `url` | `url` | `b64_json` |
|
||||
| **Usage 统计** | 不返回 | 不返回 | 返回 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 错误格式
|
||||
|
||||
图像 API 使用与 Chat Completions 相同的 OpenAI 错误格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"type": "invalid_request_error",
|
||||
"message": "Invalid size for model dall-e-3",
|
||||
"param": "size",
|
||||
"code": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 常见错误
|
||||
|
||||
| HTTP 状态码 | error.type | 说明 |
|
||||
|------------|-----------|------|
|
||||
| 400 | `invalid_request_error` | 参数错误（不支持的尺寸、无效的 prompt 等） |
|
||||
| 401 | `authentication_error` | API Key 无效或缺失 |
|
||||
| 403 | `permission_error` | 账号无权使用该模型 |
|
||||
| 429 | `rate_limit_error` | 请求频率超限 |
|
||||
| 500 | `server_error` | 服务器内部错误 |
|
||||
|
||||
### 特殊错误场景
|
||||
|
||||
| 场景 | 说明 |
|
||||
|------|------|
|
||||
| prompt 被安全系统拒绝 | `"type": "invalid_request_error"`, `"message": "Your prompt was rejected by the safety system"` |
|
||||
| 图像过大 | `"message": "Image file is too large. Maximum file size is 4MB."` |
|
||||
| 遮罩尺寸不匹配 | `"message": "Mask must have the same dimensions as the image."` |
|
||||
|
||||
---
|
||||
|
||||
## 10. 供应商适配器协议差异
|
||||
|
||||
team-api Relay 层已实现以下供应商的图像生成适配器。各供应商使用不同的上游端点和参数格式：
|
||||
|
||||
### 10.1 端点映射表
|
||||
|
||||
| 供应商 | RelayModeImagesGenerations 对应的上游端点 | 说明 |
|
||||
|--------|------------------------------------------|------|
|
||||
| **OpenAI** | `POST {baseURL}/v1/images/generations` | 原生 OpenAI 格式 |
|
||||
| **Ali（阿里云百炼）** | `POST {baseURL}/api/v1/services/aigc/text2image/image-synthesis` | DashScope 原生端点 |
|
||||
| **Baidu V2（百度文心）** | `POST {baseURL}/v2/images/generations` | 百度兼容格式 |
|
||||
| **Zhipu（智谱 AI）** | `POST {baseURL}/api/paas/v4/images/generations` | 智谱 CogView 端点 |
|
||||
| **SiliconFlow** | `POST {baseURL}/v1/images/generations` | 兼容 OpenAI 格式 |
|
||||
| **xAI（Grok）** | `POST {baseURL}/v1/images/generations` | 兼容 OpenAI 格式 |
|
||||
| **Mistral** | `POST {baseURL}/v1/images/generations` | 兼容 OpenAI 格式 |
|
||||
| **Cloudflare（Workers AI）** | `POST {baseURL}/accounts/{account_id}/ai/models/@cf/.../images/generations` | Cloudflare AI 端点 |
|
||||
| **Replicate** | `POST {baseURL}/v1/images/generations` | 兼容 OpenAI 格式 |
|
||||
| **Jimeng（即梦）** | `POST {baseURL}/v2/images/generations` | 字节跳动即梦专属端点，仅支持图像生成 |
|
||||
|
||||
### 10.2 参数转换注意事项
|
||||
|
||||
| 供应商 | 参数差异 |
|
||||
|--------|---------|
|
||||
| **Ali** | 请求体需要转换为 DashScope 格式（`input.prompt`、`parameters.size` 等），响应需要从 DashScope 格式转回 OpenAI 格式 |
|
||||
| **SiliconFlow** | `size` 字段需重命名为 `image_size` |
|
||||
| **Jimeng** | 仅支持 `RelayModeImagesGenerations`，不支持其他模式 |
|
||||
| **Replicate** | 仅支持 `RelayModeImagesGenerations`，不支持其他模式 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 协议转换注意事项
|
||||
|
||||
### 11.1 当前实现状态
|
||||
|
||||
team-api 中图像生成的处理链路：
|
||||
|
||||
```
|
||||
客户端请求 POST /v1/images/generations
|
||||
→ Path2RelayMode 识别为 RelayModeImagesGenerations
|
||||
→ HandleImagesGenerations 入口
|
||||
→ RelayHandler 统一调度
|
||||
→ 渠道适配器 GetRequestURL（构建上游 URL）
|
||||
→ 渠道适配器 ConvertRequest（转换请求参数）
|
||||
→ 渠道适配器 DoRequest（发送上游请求）
|
||||
→ 渠道适配器 DoResponse（处理上游响应）
|
||||
```
|
||||
|
||||
### 11.2 DTO 定义（当前）
|
||||
|
||||
当前 `relay/dto/usage.go` 中的图像相关结构体：
|
||||
|
||||
```go
|
||||
// ImageRequest 图像生成请求
|
||||
type ImageRequest struct {
|
||||
Model string `json:"model"`
|
||||
Prompt string `json:"prompt"`
|
||||
N *int `json:"n,omitempty"`
|
||||
Size string `json:"size,omitempty"`
|
||||
Quality string `json:"quality,omitempty"`
|
||||
ResponseFormat string `json:"response_format,omitempty"`
|
||||
Style string `json:"style,omitempty"`
|
||||
User string `json:"user,omitempty"`
|
||||
}
|
||||
|
||||
// ImageResponse 图像生成响应
|
||||
type ImageResponse struct {
|
||||
Created int64 `json:"created"`
|
||||
Data []ImageData `json:"data"`
|
||||
}
|
||||
|
||||
// ImageData 单个图像数据
|
||||
type ImageData struct {
|
||||
URL string `json:"url,omitempty"`
|
||||
B64JSON string `json:"b64_json,omitempty"`
|
||||
RevisedPrompt string `json:"revised_prompt,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
### 11.3 待完善项
|
||||
|
||||
1. **GPT Image 新参数未覆盖**：当前 `ImageRequest` 缺少 `background`、`output_format`、`output_compression`、`partial_images`、`stream`、`moderation` 字段
|
||||
2. **GPT Image 增强响应未覆盖**：当前 `ImageResponse` 缺少 `background`、`output_format`、`size`、`quality`、`usage` 字段
|
||||
3. **图像编辑端点未注册**：`/v1/images/edits` 路径尚未在 `Path2RelayMode` 中注册
|
||||
4. **图像变体端点未注册**：`/v1/images/variations` 路径尚未在 `Path2RelayMode` 中注册
|
||||
5. **流式图像响应未实现**：GPT Image 的 SSE 流式响应需要专门的流处理器
|
||||
6. **Usage 统计缺失**：当前 `handleImageResponse` 返回空的 `Usage{}`，GPT Image 模型应返回实际的 token 用量
|
||||
7. **计费缺失**：DALL-E 和 GPT Image 的定价模型不同（DALL-E 按次计费，GPT Image 按 token 计费），需要区分
|
||||
|
||||
### 11.4 DTO 扩展建议
|
||||
|
||||
为支持 GPT Image 的完整功能，建议扩展 DTO：
|
||||
|
||||
```go
|
||||
// ImageRequest 图像生成请求（扩展版）
|
||||
type ImageRequest struct {
|
||||
Model string `json:"model"`
|
||||
Prompt string `json:"prompt"`
|
||||
N *int `json:"n,omitempty"`
|
||||
Size string `json:"size,omitempty"`
|
||||
Quality string `json:"quality,omitempty"`
|
||||
ResponseFormat string `json:"response_format,omitempty"`
|
||||
Style string `json:"style,omitempty"`
|
||||
Background string `json:"background,omitempty"` // GPT Image: transparent/opaque/auto
|
||||
OutputFormat string `json:"output_format,omitempty"` // GPT Image: png/jpeg/webp
|
||||
OutputCompression *int `json:"output_compression,omitempty"` // GPT Image: 0-100
|
||||
PartialImages *int `json:"partial_images,omitempty"` // GPT Image: 0-3
|
||||
Stream *bool `json:"stream,omitempty"` // GPT Image: 流式
|
||||
Moderation string `json:"moderation,omitempty"` // GPT Image: auto/low
|
||||
User string `json:"user,omitempty"`
|
||||
}
|
||||
|
||||
// ImageResponse 图像生成响应（扩展版）
|
||||
type ImageResponse struct {
|
||||
Created int64 `json:"created"`
|
||||
Data []ImageData `json:"data"`
|
||||
Background string `json:"background,omitempty"`
|
||||
OutputFormat string `json:"output_format,omitempty"`
|
||||
Size string `json:"size,omitempty"`
|
||||
Quality string `json:"quality,omitempty"`
|
||||
Usage *ImageUsage `json:"usage,omitempty"`
|
||||
}
|
||||
|
||||
// ImageUsage GPT Image token 用量
|
||||
type ImageUsage struct {
|
||||
TotalTokens int `json:"total_tokens"`
|
||||
InputTokens int `json:"input_tokens"`
|
||||
OutputTokens int `json:"output_tokens"`
|
||||
InputTokenDetails *ImageTokenDetails `json:"input_tokens_details,omitempty"`
|
||||
}
|
||||
|
||||
// ImageTokenDetails GPT Image 输入 token 细分
|
||||
type ImageTokenDetails struct {
|
||||
TextTokens int `json:"text_tokens"`
|
||||
ImageTokens int `json:"image_tokens"`
|
||||
}
|
||||
```
|
||||
|
||||
### 11.5 新增 RelayMode 建议
|
||||
|
||||
为支持图像编辑和变体端点，建议在 `relay/constant/relay_mode.go` 中新增：
|
||||
|
||||
```go
|
||||
RelayModeImagesEdits // /v1/images/edits
|
||||
RelayModeImagesVariations // /v1/images/variations
|
||||
```
|
||||
|
||||
并在 `Path2RelayMode` 中添加路径匹配：
|
||||
|
||||
```go
|
||||
case strings.HasSuffix(path, "/images/edits"):
|
||||
result = RelayModeImagesEdits
|
||||
case strings.HasSuffix(path, "/images/variations"):
|
||||
result = RelayModeImagesVariations
|
||||
```
|
||||
|
||||
### 11.6 计费差异
|
||||
|
||||
| 模型 | 计费方式 | 说明 |
|
||||
|------|---------|------|
|
||||
| `dall-e-2` | 按次计费 | 根据尺寸和数量定价，与 token 无关 |
|
||||
| `dall-e-3` | 按次计费 | quality=hd 价格高于 standard |
|
||||
| `gpt-image-1` | 按 token 计费 | 使用 `usage` 字段中的 token 数计费 |
|
||||
| `gpt-image-1-mini` | 按 token 计费 | 价格低于 gpt-image-1 |
|
||||
| `gpt-image-1.5` | 按 token 计费 | 价格低于 gpt-image-1 |
|
||||
|
||||
Relay 层的 `BillingProvider` 需要根据模型类型选择不同的计费策略：DALL-E 模型使用固定价格计费，GPT Image 模型使用 token 计费。当前 `handleImageResponse` 返回空 Usage，需要区分处理。
|
||||
@@ -0,0 +1,745 @@
|
||||
# Stability AI 图像生成 API 文档
|
||||
|
||||
## 概述
|
||||
|
||||
Stability AI 是 Stable Diffusion 模型的创建者，提供图像生成 REST API（v2beta）。API 基于 Stable Image 品牌提供服务，支持文生图、图生图、局部重绘、超分辨率、背景移除等功能。
|
||||
|
||||
- **官方文档**：https://platform.stability.ai/docs
|
||||
- **API Base URL**：`https://api.stability.ai`
|
||||
- **API 版本**：v2beta（当前最新）
|
||||
- **认证方式**：Bearer Token（API Key）
|
||||
- **协议格式**：REST + multipart/form-data（部分接口支持 JSON）
|
||||
|
||||
## 认证
|
||||
|
||||
### 获取 API Key
|
||||
|
||||
1. 注册 https://platform.stability.ai 账号
|
||||
2. 在 Account Settings → API Keys 页面创建 Key
|
||||
3. 使用 Bearer Token 认证
|
||||
|
||||
### 认证头
|
||||
|
||||
```
|
||||
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
### 计费方式
|
||||
|
||||
- 按 Credit 消耗计费，不同模型/服务消耗不同 Credit
|
||||
- 免费账户有初始 Credit
|
||||
- Credit 可在平台购买
|
||||
|
||||
## 核心概念
|
||||
|
||||
### Stable Image 服务
|
||||
|
||||
Stability AI 的图像生成服务按功能分为以下类别：
|
||||
|
||||
| 服务 | 说明 | 核心端点路径 |
|
||||
|------|------|-------------|
|
||||
| Text to Image | 文生图 | `/v2beta/stable-image/generate/{model}` |
|
||||
| Image to Image | 图生图 | `/v2beta/stable-image/generate/{model}` |
|
||||
| Inpaint / Outpaint | 局部重绘/外扩 | `/v2beta/stable-image/generate/{model}` |
|
||||
| Upscale | 超分辨率放大 | `/v2beta/stable-image/upscale/{model}` |
|
||||
| Remove Background | 背景移除 | `/v2beta/stable-image/remove-bg` |
|
||||
| Search and Replace | 搜索替换 | `/v2beta/stable-image/generate/{model}` |
|
||||
|
||||
### 可用模型
|
||||
|
||||
| 模型 ID | 说明 | 特点 |
|
||||
|---------|------|------|
|
||||
| `sd3` | Stable Diffusion 3 | 高质量文生图，支持 T5 文本编码器 |
|
||||
| `sd3-turbo` | SD3 Turbo | 快速生成，适合高吞吐场景 |
|
||||
| `sd3.5-large` | Stable Diffusion 3.5 Large | 最新旗舰模型，最高质量 |
|
||||
| `sd3.5-large-turbo` | SD3.5 Large Turbo | 旗舰快速版 |
|
||||
| `sd3.5-medium` | Stable Diffusion 3.5 Medium | 质量与速度平衡 |
|
||||
| `sdxl` | Stable Diffusion XL | 上代旗舰，广泛支持 |
|
||||
| `sdxl-turbo` | SDXL Turbo | SDXL 快速版 |
|
||||
| `core` | Stable Image Core | 通用高质量模型 |
|
||||
| `ultra` | Stable Image Ultra | 最高质量，4 步生成 |
|
||||
|
||||
### 模型选择建议
|
||||
|
||||
| 场景 | 推荐模型 | 原因 |
|
||||
|------|---------|------|
|
||||
| 最高质量 | `sd3.5-large` 或 `ultra` | 旗舰级输出 |
|
||||
| 质量与速度平衡 | `sd3.5-medium` 或 `core` | 性价比最优 |
|
||||
| 快速批量生成 | `sd3-turbo` 或 `sd3.5-large-turbo` | 最低延迟 |
|
||||
| 兼容性最佳 | `sdxl` | 社区生态最丰富 |
|
||||
|
||||
## API 端点详解
|
||||
|
||||
### 1. 文生图（Text to Image）
|
||||
|
||||
根据文本提示词生成图像。
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
POST https://api.stability.ai/v2beta/stable-image/generate/{model}
|
||||
```
|
||||
|
||||
**Headers**
|
||||
|
||||
| Header | 值 | 必填 | 说明 |
|
||||
|--------|---|------|------|
|
||||
| `Authorization` | `Bearer sk-xxx` | 是 | API Key 认证 |
|
||||
| `Content-Type` | `multipart/form-data` | 是 | 请求体格式 |
|
||||
| `Accept` | `image/*` 或 `application/json` | 是 | 响应格式。`image/*` 直接返回图像二进制；`application/json` 返回 base64 编码 |
|
||||
|
||||
**Body 参数（multipart/form-data）**
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| `prompt` | string | 是 | — | 正向提示词，描述期望生成的图像内容 |
|
||||
| `negative_prompt` | string | 否 | `""` | 反向提示词，描述不希望出现的内容（部分模型支持） |
|
||||
| `aspect_ratio` | string | 否 | `"1:1"` | 宽高比。可选值：`"1:1"`, `"16:9"`, `"21:9"`, `"2:3"`, `"3:2"`, `"4:5"`, `"5:4"`, `"9:16"`, `"9:21"` |
|
||||
| `seed` | integer | 否 | 随机 | 随机种子，相同种子+参数可复现结果。范围：0 ~ 4294967294 |
|
||||
| `output_format` | string | 否 | `"png"` | 输出格式。可选值：`"png"`, `"jpeg"`, `"webp"` |
|
||||
| `mode` | string | 否 | `"text-to-image"` | 生成模式。文生图使用 `"text-to-image"` |
|
||||
| `model` | string | 否 | URL 中的模型 | 覆盖 URL 路径中指定的模型（部分场景可用） |
|
||||
| `style_preset` | string | 否 | 无 | 预设风格（见下方风格列表） |
|
||||
|
||||
**示例请求**
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
https://api.stability.ai/v2beta/stable-image/generate/sd3.5-large \
|
||||
-H "Authorization: Bearer sk-xxxxxxxx" \
|
||||
-H "Accept: image/*" \
|
||||
-F "prompt=A majestic lion standing on a cliff at sunset, cinematic lighting, 8k" \
|
||||
-F "output_format=png" \
|
||||
-F "aspect_ratio=16:9" \
|
||||
-F "seed=42" \
|
||||
-o lion.png
|
||||
```
|
||||
|
||||
**示例请求（JSON 响应）**
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
https://api.stability.ai/v2beta/stable-image/generate/sd3.5-large \
|
||||
-H "Authorization: Bearer sk-xxxxxxxx" \
|
||||
-H "Accept: application/json" \
|
||||
-F "prompt=A majestic lion standing on a cliff at sunset" \
|
||||
-F "output_format=png"
|
||||
```
|
||||
|
||||
**JSON 响应格式**
|
||||
|
||||
```json
|
||||
{
|
||||
"image": "iVBORw0KGgoAAAANSUhEUgAA...",
|
||||
"seed": 42,
|
||||
"finish_reason": "SUCCESS"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `image` | string | Base64 编码的图像数据 |
|
||||
| `seed` | integer | 使用的随机种子 |
|
||||
| `finish_reason` | string | 完成原因。`"SUCCESS"` 表示成功 |
|
||||
|
||||
**二进制响应**
|
||||
|
||||
当 `Accept: image/*` 时，直接返回图像二进制数据，Content-Type 为 `image/png`、`image/jpeg` 或 `image/webp`。
|
||||
|
||||
---
|
||||
|
||||
### 2. 图生图（Image to Image）
|
||||
|
||||
基于输入图像和提示词生成新图像。
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
POST https://api.stability.ai/v2beta/stable-image/generate/{model}
|
||||
```
|
||||
|
||||
**Headers**
|
||||
|
||||
与文生图相同。
|
||||
|
||||
**Body 参数（multipart/form-data）**
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| `prompt` | string | 是 | — | 提示词，描述期望的变化 |
|
||||
| `image` | file | 是 | — | 输入图像文件（PNG/JPEG/WebP） |
|
||||
| `negative_prompt` | string | 否 | `""` | 反向提示词 |
|
||||
| `strength` | float | 否 | `0.5` | 图像变化强度。0.0 = 不变，1.0 = 完全重新生成。范围：0.0 ~ 1.0 |
|
||||
| `seed` | integer | 否 | 随机 | 随机种子 |
|
||||
| `output_format` | string | 否 | `"png"` | 输出格式 |
|
||||
| `mode` | string | 否 | `"image-to-image"` | 生成模式 |
|
||||
| `style_preset` | string | 否 | 无 | 预设风格 |
|
||||
|
||||
**示例请求**
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
https://api.stability.ai/v2beta/stable-image/generate/sd3.5-large \
|
||||
-H "Authorization: Bearer sk-xxxxxxxx" \
|
||||
-H "Accept: image/*" \
|
||||
-F "prompt=Transform into a watercolor painting style" \
|
||||
-F "image=@input.jpg" \
|
||||
-F "strength=0.7" \
|
||||
-F "output_format=png" \
|
||||
-o output.png
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 局部重绘（Inpaint）
|
||||
|
||||
使用遮罩图像指定需要重绘的区域。
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
POST https://api.stability.ai/v2beta/stable-image/generate/{model}
|
||||
```
|
||||
|
||||
**Headers**
|
||||
|
||||
与文生图相同。
|
||||
|
||||
**Body 参数（multipart/form-data）**
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| `prompt` | string | 是 | — | 描述重绘区域的内容 |
|
||||
| `image` | file | 是 | — | 原始图像文件 |
|
||||
| `mask` | file | 是 | — | 遮罩图像（白色区域为需要重绘的部分，PNG 格式推荐） |
|
||||
| `negative_prompt` | string | 否 | `""` | 反向提示词 |
|
||||
| `seed` | integer | 否 | 随机 | 随机种子 |
|
||||
| `output_format` | string | 否 | `"png"` | 输出格式 |
|
||||
| `mode` | string | 否 | `"inpaint"` | 生成模式 |
|
||||
|
||||
**示例请求**
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
https://api.stability.ai/v2beta/stable-image/generate/sd3.5-large \
|
||||
-H "Authorization: Bearer sk-xxxxxxxx" \
|
||||
-H "Accept: image/*" \
|
||||
-F "prompt=A beautiful blue sky with fluffy clouds" \
|
||||
-F "image=@original.png" \
|
||||
-F "mask=@mask.png" \
|
||||
-F "mode=inpaint" \
|
||||
-o inpainted.png
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 外扩（Outpaint）
|
||||
|
||||
扩展图像边界，在原始图像外部生成新内容。
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
POST https://api.stability.ai/v2beta/stable-image/generate/{model}
|
||||
```
|
||||
|
||||
**Body 参数**
|
||||
|
||||
与局部重绘类似，但 `mode` 设置为 `"outpaint"`。可通过 `left`、`right`、`up`、`down` 参数指定各方向的扩展像素数。
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| `prompt` | string | 是 | — | 描述扩展区域的内容 |
|
||||
| `image` | file | 是 | — | 原始图像 |
|
||||
| `left` | integer | 否 | `0` | 左侧扩展像素数 |
|
||||
| `right` | integer | 否 | `0` | 右侧扩展像素数 |
|
||||
| `up` | integer | 否 | `0` | 上方扩展像素数 |
|
||||
| `down` | integer | 否 | `0` | 下方扩展像素数 |
|
||||
| `seed` | integer | 否 | 随机 | 随机种子 |
|
||||
| `output_format` | string | 否 | `"png"` | 输出格式 |
|
||||
| `mode` | string | 否 | `"outpaint"` | 生成模式 |
|
||||
|
||||
---
|
||||
|
||||
### 5. 超分辨率（Upscale）
|
||||
|
||||
放大图像并增强细节。
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
POST https://api.stability.ai/v2beta/stable-image/upscale/{model}
|
||||
```
|
||||
|
||||
**可用 Upscale 模型**
|
||||
|
||||
| 模型 ID | 说明 |
|
||||
|---------|------|
|
||||
| `creative` | 创意增强（添加新细节） |
|
||||
| `fast` | 快速放大 |
|
||||
| `conservative` | 保守放大（保持原始风格） |
|
||||
|
||||
**Body 参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| `image` | file | 是 | — | 需要放大的图像 |
|
||||
| `prompt` | string | 否 | `""` | 提示词，引导放大时的细节增强方向（`creative` 模式推荐） |
|
||||
| `negative_prompt` | string | 否 | `""` | 反向提示词 |
|
||||
| `seed` | integer | 否 | 随机 | 随机种子 |
|
||||
| `output_format` | string | 否 | `"png"` | 输出格式 |
|
||||
| `creativity` | float | 否 | `0.5` | 创意度（仅 `creative` 模式）。范围：0.0 ~ 1.0 |
|
||||
|
||||
**示例请求**
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
https://api.stability.ai/v2beta/stable-image/upscale/creative \
|
||||
-H "Authorization: Bearer sk-xxxxxxxx" \
|
||||
-H "Accept: image/*" \
|
||||
-F "image=@low_res.png" \
|
||||
-F "prompt=Enhance details, add texture" \
|
||||
-F "creativity=0.7" \
|
||||
-o upscaled.png
|
||||
```
|
||||
|
||||
**注意**：Upscale 结果可能是异步的。如果图像较大，API 可能返回 `202 Accepted`，需要轮询获取结果。
|
||||
|
||||
---
|
||||
|
||||
### 6. 背景移除（Remove Background）
|
||||
|
||||
自动识别并移除图像背景。
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
POST https://api.stability.ai/v2beta/stable-image/remove-bg
|
||||
```
|
||||
|
||||
**Body 参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| `image` | file | 是 | — | 输入图像 |
|
||||
| `output_format` | string | 否 | `"png"` | 输出格式（推荐 PNG 以保留透明度） |
|
||||
|
||||
**示例请求**
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
https://api.stability.ai/v2beta/stable-image/remove-bg \
|
||||
-H "Authorization: Bearer sk-xxxxxxxx" \
|
||||
-H "Accept: image/*" \
|
||||
-F "image=@photo.jpg" \
|
||||
-F "output_format=png" \
|
||||
-o no_bg.png
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. 搜索替换（Search and Replace）
|
||||
|
||||
在图像中查找特定内容并替换为提示词描述的新内容。
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
POST https://api.stability.ai/v2beta/stable-image/generate/{model}
|
||||
```
|
||||
|
||||
**Body 参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| `prompt` | string | 是 | — | 替换后的内容描述 |
|
||||
| `image` | file | 是 | — | 原始图像 |
|
||||
| `search_prompt` | string | 是 | — | 要查找/替换的内容描述 |
|
||||
| `negative_prompt` | string | 否 | `""` | 反向提示词 |
|
||||
| `seed` | integer | 否 | 随机 | 随机种子 |
|
||||
| `output_format` | string | 否 | `"png"` | 输出格式 |
|
||||
| `mode` | string | 否 | `"search-and-replace"` | 生成模式 |
|
||||
|
||||
## 风格预设（Style Presets）
|
||||
|
||||
以下风格预设可用于 `style_preset` 参数：
|
||||
|
||||
| 类别 | 预设名称 |
|
||||
|------|---------|
|
||||
| 3D | `3d-model` |
|
||||
| 摄影风格 | `analog-film`, `cinematic`, `photographic` |
|
||||
| 动漫 | `anime`, `comic-book`, `line-art` |
|
||||
| 数字艺术 | `digital-art`, `enhance`, `isometric`, `low-poly`, `pixel-art` |
|
||||
| 绘画 | `craft-clay`, `fantasy-art`, `neon-punk`, `origami`, `stained-glass`, `watercolor`, `tile-texture` |
|
||||
| 其他 | `anime`, `aztec-jungle`, `blockprint`, `collage`, `conceptual-art`, `diagram`, `fashion`, `filmic`, ` hdr`, `tile-texture`, `thriller`, `ukiyo-e`, `vintage`, `vivid-colors` |
|
||||
|
||||
## SDK 参数参考
|
||||
|
||||
Stability AI 提供官方 Python SDK（`stability-sdk`），以下参数在 SDK 和 REST API 中通用：
|
||||
|
||||
### 通用参数
|
||||
|
||||
| 参数 | CLI 参数 | 类型 | 默认值 | 说明 |
|
||||
|------|---------|------|--------|------|
|
||||
| 宽度 | `--width` | integer | 1024 | 输出图像宽度（像素） |
|
||||
| 高度 | `--height` | integer | 1024 | 输出图像高度（像素） |
|
||||
| CFG Scale | `--cfg_scale` | float | 7.0 | 提示词相关性/分类器自由引导尺度。范围：1 ~ 35 |
|
||||
| 采样器 | `--sampler` | string | 自动 | 采样算法（见下方采样器列表） |
|
||||
| 步数 | `--steps` | integer | 30 | 扩散步数。范围：10 ~ 50（Turbo 模型推荐 4） |
|
||||
| 种子 | `--seed` | integer | 随机 | 随机种子。范围：0 ~ 4294967294 |
|
||||
| 初始图像 | `--init_image` | file | 无 | 图生图输入图像 |
|
||||
| 遮罩图像 | `--mask_image` | file | 无 | 局部重绘遮罩 |
|
||||
| 引擎 | `--engine` | string | 自动 | 模型/引擎 ID |
|
||||
| 样式预设 | `--style_preset` | string | 无 | 风格预设 |
|
||||
|
||||
### 采样器（Sampler）
|
||||
|
||||
| 采样器 ID | 说明 |
|
||||
|-----------|------|
|
||||
| `ddim` | DDIM 采样器 |
|
||||
| `plms` | PLMS 采样器 |
|
||||
| `k_euler` | Euler 采样器 |
|
||||
| `k_euler_ancestral` | Euler Ancestral 采样器 |
|
||||
| `k_heun` | Heun 采样器 |
|
||||
| `k_dpm_2` | DPM2 采样器 |
|
||||
| `k_dpm_2_ancestral` | DPM2 Ancestral 采样器 |
|
||||
| `k_dpmpp_2s_ancestral` | DPM++ 2S Ancestral 采样器 |
|
||||
| `k_dpmpp_sde` | DPM++ SDE 采样器 |
|
||||
| `k_dpmpp_2m` | DPM++ 2M 采样器 |
|
||||
| `k_dpmpp_2m_sde` | DPM++ 2M SDE 采样器 |
|
||||
| `k_dpmpp_3m_sde` | DPM++ 3M SDE 采样器 |
|
||||
|
||||
## 错误处理
|
||||
|
||||
### HTTP 状态码
|
||||
|
||||
| 状态码 | 含义 |
|
||||
|--------|------|
|
||||
| `200` | 成功 |
|
||||
| `202` | 已接受（异步任务，需轮询） |
|
||||
| `400` | 请求参数错误 |
|
||||
| `401` | 认证失败（API Key 无效） |
|
||||
| `402` | Credit 不足 |
|
||||
| `403` | 无权限 |
|
||||
| `404` | 模型/端点不存在 |
|
||||
| `413` | 请求体过大 |
|
||||
| `429` | 请求频率超限 |
|
||||
| `500` | 服务器内部错误 |
|
||||
|
||||
### 错误响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "6a6c3a9e-ee82-4e94-b36e-5b3f14e4c631",
|
||||
"message": "Invalid request: prompt is required",
|
||||
"name": "bad_request"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | string | 错误唯一标识 |
|
||||
| `message` | string | 错误描述 |
|
||||
| `name` | string | 错误类型名称 |
|
||||
|
||||
### 常见错误类型
|
||||
|
||||
| 错误类型 name | HTTP 状态码 | 说明 |
|
||||
|--------------|------------|------|
|
||||
| `bad_request` | 400 | 请求参数错误 |
|
||||
| `unauthorized` | 401 | API Key 无效或缺失 |
|
||||
| `insufficient_credits` | 402 | Credit 余额不足 |
|
||||
| `permission_denied` | 403 | 无权访问该模型/功能 |
|
||||
| `not_found` | 404 | 资源不存在 |
|
||||
| `rate_limit_exceeded` | 429 | 请求频率超限 |
|
||||
| `server_error` | 500 | 服务器内部错误 |
|
||||
|
||||
## 异步操作
|
||||
|
||||
### 提交异步任务
|
||||
|
||||
对于耗时操作（如 Upscale），API 可能返回 `202 Accepted`：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "abc123",
|
||||
"status": "in-progress"
|
||||
}
|
||||
```
|
||||
|
||||
### 轮询结果
|
||||
|
||||
```
|
||||
GET https://api.stability.ai/v2beta/stable-image/results/{id}
|
||||
```
|
||||
|
||||
**Headers**
|
||||
|
||||
```
|
||||
Authorization: Bearer sk-xxx
|
||||
Accept: image/* 或 application/json
|
||||
```
|
||||
|
||||
### 响应状态
|
||||
|
||||
| 状态 | 说明 |
|
||||
|------|------|
|
||||
| `in-progress` | 正在处理 |
|
||||
| `complete` | 已完成（返回图像） |
|
||||
| `failed` | 处理失败 |
|
||||
|
||||
### 轮询建议
|
||||
|
||||
- 使用指数退避策略
|
||||
- 建议初始间隔 1 秒，最大间隔 10 秒
|
||||
- 总超时建议 5 分钟
|
||||
|
||||
## 速率限制
|
||||
|
||||
| 计划 | 并发请求数 | 每秒请求数 |
|
||||
|------|-----------|-----------|
|
||||
| Free | 2 | 2 |
|
||||
| Basic | 4 | 4 |
|
||||
| Standard | 8 | 8 |
|
||||
| Premium | 16 | 16 |
|
||||
| Enterprise | 自定义 | 自定义 |
|
||||
|
||||
速率限制响应头：
|
||||
|
||||
```
|
||||
X-RateLimit-Limit: 100
|
||||
X-RateLimit-Remaining: 95
|
||||
X-RateLimit-Reset: 1677652288
|
||||
```
|
||||
|
||||
## 图像尺寸与限制
|
||||
|
||||
### 支持的宽高比
|
||||
|
||||
| 宽高比 | 尺寸（像素） | 说明 |
|
||||
|--------|-------------|------|
|
||||
| `1:1` | 1024 × 1024 | 正方形（默认） |
|
||||
| `16:9` | 1344 × 768 | 横屏宽幅 |
|
||||
| `21:9` | 1536 × 640 | 超宽屏 |
|
||||
| `2:3` | 768 × 1152 | 竖屏 |
|
||||
| `3:2` | 1152 × 768 | 横屏 |
|
||||
| `4:5` | 896 × 1088 | 近正方形竖屏 |
|
||||
| `5:4` | 1088 × 896 | 近正方形横屏 |
|
||||
| `9:16` | 768 × 1344 | 竖屏长幅 |
|
||||
| `9:21` | 640 × 1536 | 超长竖屏 |
|
||||
|
||||
### 文件大小限制
|
||||
|
||||
- 输入图像：最大 10MB
|
||||
- 输出图像：最大 20MB
|
||||
|
||||
## Python SDK 使用示例
|
||||
|
||||
### 安装
|
||||
|
||||
```bash
|
||||
pip install stability-sdk
|
||||
```
|
||||
|
||||
### 文生图
|
||||
|
||||
```python
|
||||
import io
|
||||
import requests
|
||||
from PIL import Image
|
||||
|
||||
response = requests.post(
|
||||
"https://api.stability.ai/v2beta/stable-image/generate/sd3.5-large",
|
||||
headers={
|
||||
"Authorization": f"Bearer {api_key}",
|
||||
"Accept": "image/*"
|
||||
},
|
||||
files={"none": ""},
|
||||
data={
|
||||
"prompt": "A beautiful mountain landscape at golden hour",
|
||||
"output_format": "png",
|
||||
"aspect_ratio": "16:9",
|
||||
}
|
||||
)
|
||||
|
||||
if response.status_code == 200:
|
||||
with open("output.png", "wb") as f:
|
||||
f.write(response.content)
|
||||
else:
|
||||
print(f"Error: {response.status_code}")
|
||||
print(response.json())
|
||||
```
|
||||
|
||||
### 图生图
|
||||
|
||||
```python
|
||||
response = requests.post(
|
||||
"https://api.stability.ai/v2beta/stable-image/generate/sd3.5-large",
|
||||
headers={
|
||||
"Authorization": f"Bearer {api_key}",
|
||||
"Accept": "image/*"
|
||||
},
|
||||
files={
|
||||
"image": open("input.jpg", "rb")
|
||||
},
|
||||
data={
|
||||
"prompt": "Transform into oil painting style",
|
||||
"strength": 0.7,
|
||||
"output_format": "png",
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### 局部重绘
|
||||
|
||||
```python
|
||||
response = requests.post(
|
||||
"https://api.stability.ai/v2beta/stable-image/generate/sd3.5-large",
|
||||
headers={
|
||||
"Authorization": f"Bearer {api_key}",
|
||||
"Accept": "image/*"
|
||||
},
|
||||
files={
|
||||
"image": open("original.png", "rb"),
|
||||
"mask": open("mask.png", "rb"),
|
||||
},
|
||||
data={
|
||||
"prompt": "A clear blue sky with white clouds",
|
||||
"output_format": "png",
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Go HTTP 调用示例
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"fmt"
|
||||
"io"
|
||||
"mime/multipart"
|
||||
"net/http"
|
||||
"os"
|
||||
)
|
||||
|
||||
func generateImage(apiKey, prompt, model, outputPath string) error {
|
||||
var buf bytes.Buffer
|
||||
writer := multipart.NewWriter(&buf)
|
||||
|
||||
_ = writer.WriteField("prompt", prompt)
|
||||
_ = writer.WriteField("output_format", "png")
|
||||
_ = writer.WriteField("aspect_ratio", "1:1")
|
||||
|
||||
// 必须有一个 none 字段（当没有文件上传时）
|
||||
part, _ := writer.CreateFormFile("none", "")
|
||||
part.Write([]byte{})
|
||||
|
||||
writer.Close()
|
||||
|
||||
url := fmt.Sprintf("https://api.stability.ai/v2beta/stable-image/generate/%s", model)
|
||||
req, _ := http.NewRequest("POST", url, &buf)
|
||||
req.Header.Set("Authorization", "Bearer "+apiKey)
|
||||
req.Header.Set("Accept", "image/*")
|
||||
req.Header.Set("Content-Type", writer.FormDataContentType())
|
||||
|
||||
resp, err := http.DefaultClient.Do(req)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
|
||||
if resp.StatusCode != 200 {
|
||||
body, _ := io.ReadAll(resp.Body)
|
||||
return fmt.Errorf("API error %d: %s", resp.StatusCode, body)
|
||||
}
|
||||
|
||||
file, _ := os.Create(outputPath)
|
||||
defer file.Close()
|
||||
io.Copy(file, resp.Body)
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
## 与 OpenAI Images API 的对比
|
||||
|
||||
| 特性 | Stability AI | OpenAI Images |
|
||||
|------|-------------|---------------|
|
||||
| 认证方式 | Bearer Token | Bearer Token |
|
||||
| 请求格式 | multipart/form-data | JSON |
|
||||
| 文生图 | `/v2beta/stable-image/generate/{model}` | `/v1/images/generations` |
|
||||
| 图生图 | 同端点 + image 文件 | `/v1/images/edits` |
|
||||
| 局部重绘 | 同端点 + mask 文件 | `/v1/images/edits` + mask |
|
||||
| 超分辨率 | `/v2beta/stable-image/upscale/{model}` | 不支持 |
|
||||
| 背景移除 | `/v2beta/stable-image/remove-bg` | 不支持 |
|
||||
| 响应格式 | 二进制或 JSON（base64） | JSON（URL 或 base64） |
|
||||
| 流式支持 | 不支持 | gpt-image-1 支持 SSE |
|
||||
| 模型数量 | 10+ | 5（DALL-E 2/3, GPT Image 系列） |
|
||||
| 风格控制 | style_preset + sampler + steps | quality + style |
|
||||
| 免费额度 | 初始 Credit | 无（按次付费） |
|
||||
|
||||
## team-api 适配器实现参考
|
||||
|
||||
### 端点映射
|
||||
|
||||
| team-api 入口 | Stability AI 上游 |
|
||||
|--------------|------------------|
|
||||
| `POST /v1/images/generations` | `POST /v2beta/stable-image/generate/{model}` |
|
||||
| `POST /v1/images/edits` | `POST /v2beta/stable-image/generate/{model}` (mode=image-to-image) |
|
||||
| `POST /v1/images/variations` | `POST /v2beta/stable-image/generate/{model}` (mode=image-to-image) |
|
||||
|
||||
### 请求转换要点
|
||||
|
||||
1. **认证转换**：OpenAI 格式 `Bearer sk-xxx` → Stability 格式 `Bearer sk-xxx`（直接透传 API Key）
|
||||
2. **请求体转换**：
|
||||
- OpenAI JSON body → multipart/form-data
|
||||
- `size` → `aspect_ratio`（需要尺寸映射逻辑）
|
||||
- `n` 参数：Stability API 不支持批量生成，需要循环调用
|
||||
- `response_format` → `Accept` header（`url` → 不支持，`b64_json` → `application/json`）
|
||||
3. **响应体转换**：
|
||||
- Stability 二进制响应 → OpenAI JSON 格式（base64 编码）
|
||||
- Stability JSON 响应 → 提取 `image` 字段 → 放入 OpenAI `data[].b64_json`
|
||||
|
||||
### DTO 参考
|
||||
|
||||
```go
|
||||
// Stability AI 请求参数（转换后）
|
||||
type StabilityImageRequest struct {
|
||||
Prompt string `json:"prompt"`
|
||||
NegativePrompt string `json:"negative_prompt,omitempty"`
|
||||
AspectRatio string `json:"aspect_ratio,omitempty"`
|
||||
Seed uint32 `json:"seed,omitempty"`
|
||||
OutputFormat string `json:"output_format,omitempty"`
|
||||
Mode string `json:"mode,omitempty"`
|
||||
Strength float64 `json:"strength,omitempty"`
|
||||
StylePreset string `json:"style_preset,omitempty"`
|
||||
}
|
||||
|
||||
// Stability AI JSON 响应
|
||||
type StabilityImageResponse struct {
|
||||
Image string `json:"image"`
|
||||
Seed uint32 `json:"seed"`
|
||||
FinishReason string `json:"finish_reason"`
|
||||
}
|
||||
|
||||
// Stability AI 错误响应
|
||||
type StabilityError struct {
|
||||
ID string `json:"id"`
|
||||
Message string `json:"message"`
|
||||
Name string `json:"name"`
|
||||
}
|
||||
```
|
||||
|
||||
### 尺寸映射表
|
||||
|
||||
| OpenAI size | Stability aspect_ratio |
|
||||
|-------------|----------------------|
|
||||
| `256x256` | `1:1`（SDXL 不支持 256，降质） |
|
||||
| `512x512` | `1:1`（SDXL 不支持 512，降质） |
|
||||
| `1024x1024` | `1:1` |
|
||||
| `1792x1024` | `16:9` |
|
||||
| `1024x1792` | `9:16` |
|
||||
| `1536x1024` | `3:2` |
|
||||
| `1024x1536` | `2:3` |
|
||||
@@ -0,0 +1,167 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.bigmodel.cn/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# 图像生成(异步)
|
||||
|
||||
> 使用 [GLM-Image](/cn/guide/models/image-generation/glm-image) 系列模型从文本提示生成高质量图像。通过对用户文字描述快速、精准的理解，让 `AI` 的图像表达更加精确和个性化。仅支持 `GLM-Image` 模型。
|
||||
|
||||
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml /openapi/openapi.json post /paas/v4/async/images/generations
|
||||
openapi: 3.0.1
|
||||
info:
|
||||
title: ZHIPU AI API
|
||||
description: ZHIPU AI 接口提供强大的 AI 能力，包括聊天对话、工具调用和视频生成。
|
||||
license:
|
||||
name: ZHIPU AI 开发者协议和政策
|
||||
url: https://chat.z.ai/legal-agreement/terms-of-service
|
||||
version: 1.0.0
|
||||
contact:
|
||||
name: Z.AI 开发者
|
||||
url: https://chat.z.ai/legal-agreement/privacy-policy
|
||||
email: user_feedback@z.ai
|
||||
servers:
|
||||
- url: https://open.bigmodel.cn/api/
|
||||
description: 开放平台服务
|
||||
security:
|
||||
- bearerAuth: []
|
||||
tags:
|
||||
- name: 模型 API
|
||||
description: Chat API
|
||||
- name: 工具 API
|
||||
description: Web Search API
|
||||
- name: Agent API
|
||||
description: Agent API
|
||||
- name: 文件 API
|
||||
description: File API
|
||||
- name: 知识库 API
|
||||
description: Knowledge API
|
||||
- name: 实时 API
|
||||
description: Realtime API
|
||||
- name: 批处理 API
|
||||
description: Batch API
|
||||
- name: 助理 API
|
||||
description: Assistant API
|
||||
- name: 智能体 API（旧）
|
||||
description: QingLiu Agent API
|
||||
paths:
|
||||
/paas/v4/async/images/generations:
|
||||
post:
|
||||
tags:
|
||||
- 模型 API
|
||||
summary: 图像生成(异步)
|
||||
description: >-
|
||||
使用 [GLM-Image](/cn/guide/models/image-generation/glm-image)
|
||||
系列模型从文本提示生成高质量图像。通过对用户文字描述快速、精准的理解，让 `AI` 的图像表达更加精确和个性化。仅支持 `GLM-Image`
|
||||
模型。
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/AsyncCreateImageRequest'
|
||||
examples:
|
||||
图像生成示例:
|
||||
value:
|
||||
model: glm-image
|
||||
prompt: 一只可爱的小猫咪，坐在阳光明媚的窗台上，背景是蓝天白云.
|
||||
size: 1280x1280
|
||||
required: true
|
||||
responses:
|
||||
'200':
|
||||
description: 业务处理成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/AsyncResponse'
|
||||
default:
|
||||
description: 请求失败。
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
components:
|
||||
schemas:
|
||||
AsyncCreateImageRequest:
|
||||
type: object
|
||||
required:
|
||||
- model
|
||||
- prompt
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 模型编码
|
||||
enum:
|
||||
- glm-image
|
||||
example: glm-image
|
||||
prompt:
|
||||
type: string
|
||||
description: 所需图像的文本描述
|
||||
example: 一只可爱的小猫咪
|
||||
quality:
|
||||
type: string
|
||||
description: '生成图像的质量。`hd`: 生成更精细、细节更丰富的图像，整体一致性更高，耗时约`20`秒；'
|
||||
enum:
|
||||
- hd
|
||||
default: hd
|
||||
size:
|
||||
type: string
|
||||
description: >-
|
||||
图片尺寸，推荐枚举值：`1280x1280` (默认), `1568×1056`, `1056×1568`, `1472×1088`,
|
||||
`1088×1472`, `1728×960`, `960×1728`。
|
||||
|
||||
自定义参数:长宽推荐设置在`1024px-2048px`范围内,并保证最大像素数不超过`2^22px`;长宽均需为`32`的整数倍。
|
||||
default: 1280x1280
|
||||
example: 1280x1280
|
||||
watermark_enabled:
|
||||
type: boolean
|
||||
description: |-
|
||||
控制`AI`生成图片时是否添加水印。
|
||||
- `true`: 默认启用`AI`生成的显式水印及隐式数字水印，符合政策要求。
|
||||
- `false`: 关闭所有水印，仅允许已签署免责声明的客户使用，签署路径：个人中心-安全管理-去水印管理
|
||||
example: true
|
||||
user_id:
|
||||
type: string
|
||||
description: >-
|
||||
终端用户的唯一`ID`，协助平台对终端用户的违规行为、生成违法及不良信息或其他滥用行为进行干预。`ID`长度要求：最少`6`个字符，最多`128`个字符。
|
||||
minLength: 6
|
||||
maxLength: 128
|
||||
AsyncResponse:
|
||||
type: object
|
||||
properties:
|
||||
model:
|
||||
description: 此次调用使用的名称。
|
||||
type: string
|
||||
id:
|
||||
description: 生成的任务`ID`，调用请求结果接口时使用此`ID`。
|
||||
type: string
|
||||
request_id:
|
||||
description: 用户在客户端请求期间提交的任务编号或平台生成的任务编号。
|
||||
type: string
|
||||
task_status:
|
||||
description: 处理状态，`PROCESSING (处理中)`、`SUCCESS (成功)`、`FAIL (失败)`。结果需要通过查询获取。
|
||||
type: string
|
||||
Error:
|
||||
type: object
|
||||
properties:
|
||||
error:
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
message:
|
||||
type: string
|
||||
securitySchemes:
|
||||
bearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
description: >-
|
||||
使用以下格式进行身份验证：Bearer [<your api
|
||||
key>](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
|
||||
|
||||
````
|
||||
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,528 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.bigmodel.cn/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# 查询异步结果
|
||||
|
||||
> 查询对话补全和视频生成异步请求的处理结果和状态。
|
||||
|
||||
|
||||
|
||||
## OpenAPI
|
||||
|
||||
````yaml /openapi/openapi.json get /paas/v4/async-result/{id}
|
||||
openapi: 3.0.1
|
||||
info:
|
||||
title: ZHIPU AI API
|
||||
description: ZHIPU AI 接口提供强大的 AI 能力，包括聊天对话、工具调用和视频生成。
|
||||
license:
|
||||
name: ZHIPU AI 开发者协议和政策
|
||||
url: https://chat.z.ai/legal-agreement/terms-of-service
|
||||
version: 1.0.0
|
||||
contact:
|
||||
name: Z.AI 开发者
|
||||
url: https://chat.z.ai/legal-agreement/privacy-policy
|
||||
email: user_feedback@z.ai
|
||||
servers:
|
||||
- url: https://open.bigmodel.cn/api/
|
||||
description: 开放平台服务
|
||||
security:
|
||||
- bearerAuth: []
|
||||
tags:
|
||||
- name: 模型 API
|
||||
description: Chat API
|
||||
- name: 工具 API
|
||||
description: Web Search API
|
||||
- name: Agent API
|
||||
description: Agent API
|
||||
- name: 文件 API
|
||||
description: File API
|
||||
- name: 知识库 API
|
||||
description: Knowledge API
|
||||
- name: 实时 API
|
||||
description: Realtime API
|
||||
- name: 批处理 API
|
||||
description: Batch API
|
||||
- name: 助理 API
|
||||
description: Assistant API
|
||||
- name: 智能体 API（旧）
|
||||
description: QingLiu Agent API
|
||||
paths:
|
||||
/paas/v4/async-result/{id}:
|
||||
get:
|
||||
tags:
|
||||
- 模型 API
|
||||
summary: 查询异步结果
|
||||
description: 查询对话补全和视频生成异步请求的处理结果和状态。
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
description: 任务 ID。
|
||||
responses:
|
||||
'200':
|
||||
description: 业务处理成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
oneOf:
|
||||
- $ref: '#/components/schemas/ChatCompletionResponse'
|
||||
title: 对话补全
|
||||
- $ref: '#/components/schemas/AsyncVideoGenerationResponse'
|
||||
title: 视频生成
|
||||
- $ref: '#/components/schemas/AsyncImageGenerationResponse'
|
||||
title: 图像生成
|
||||
text/event-stream:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ChatCompletionChunk'
|
||||
default:
|
||||
description: 请求失败。
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
components:
|
||||
schemas:
|
||||
ChatCompletionResponse:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
description: 任务 `ID`
|
||||
type: string
|
||||
request_id:
|
||||
description: 请求 `ID`
|
||||
type: string
|
||||
created:
|
||||
description: 请求创建时间，`Unix` 时间戳（秒）
|
||||
type: integer
|
||||
model:
|
||||
description: 模型名称
|
||||
type: string
|
||||
choices:
|
||||
type: array
|
||||
description: 模型响应列表
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
index:
|
||||
type: integer
|
||||
description: 结果索引
|
||||
message:
|
||||
$ref: '#/components/schemas/ChatCompletionResponseMessage'
|
||||
finish_reason:
|
||||
type: string
|
||||
description: >-
|
||||
推理终止原因。'stop’表示自然结束或触发stop词，'tool_calls’表示模型命中函数，'length’表示达到token长度限制，'sensitive’表示内容被安全审核接口拦截（用户应判断并决定是否撤回公开内容），'network_error’表示模型推理异常，'model_context_window_exceeded'表示超出模型上下文窗口。
|
||||
usage:
|
||||
type: object
|
||||
description: 调用结束时返回的 `Token` 使用统计。
|
||||
properties:
|
||||
prompt_tokens:
|
||||
type: number
|
||||
description: 用户输入的 `Token` 数量。
|
||||
completion_tokens:
|
||||
type: number
|
||||
description: 输出的 `Token` 数量
|
||||
prompt_tokens_details:
|
||||
type: object
|
||||
properties:
|
||||
cached_tokens:
|
||||
type: number
|
||||
description: 命中的缓存 `Token` 数量
|
||||
total_tokens:
|
||||
type: integer
|
||||
description: '`Token` 总数，对于 `glm-4-voice` 模型，`1`秒音频=`12.5 Tokens`，向上取整'
|
||||
video_result:
|
||||
type: array
|
||||
description: 视频生成结果。
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
url:
|
||||
type: string
|
||||
description: 视频链接。
|
||||
cover_image_url:
|
||||
type: string
|
||||
description: 视频封面链接。
|
||||
web_search:
|
||||
type: array
|
||||
description: 返回与网页搜索相关的信息，使用`WebSearchToolSchema`时返回
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
icon:
|
||||
type: string
|
||||
description: 来源网站的图标
|
||||
title:
|
||||
type: string
|
||||
description: 搜索结果的标题
|
||||
link:
|
||||
type: string
|
||||
description: 搜索结果的网页链接
|
||||
media:
|
||||
type: string
|
||||
description: 搜索结果网页的媒体来源名称
|
||||
publish_date:
|
||||
type: string
|
||||
description: 网站发布时间
|
||||
content:
|
||||
type: string
|
||||
description: 搜索结果网页引用的文本内容
|
||||
refer:
|
||||
type: string
|
||||
description: 角标序号
|
||||
content_filter:
|
||||
type: array
|
||||
description: 返回内容安全的相关信息
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
role:
|
||||
type: string
|
||||
description: >-
|
||||
安全生效环节，包括 `role = assistant` 模型推理，`role = user` 用户输入，`role =
|
||||
history` 历史上下文
|
||||
level:
|
||||
type: integer
|
||||
description: 严重程度 `level 0-3`，`level 0`表示最严重，`3`表示轻微
|
||||
AsyncVideoGenerationResponse:
|
||||
type: object
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 模型名称。
|
||||
task_status:
|
||||
type: string
|
||||
description: 任务处理状态，`PROCESSING`（处理中），`SUCCESS`（成功），`FAIL`（失败） 注：处理中状态需通过查询获取结果
|
||||
video_result:
|
||||
type: array
|
||||
description: 数组，包含生成的视频`URL`。
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
url:
|
||||
type: string
|
||||
description: 视频链接。
|
||||
cover_image_url:
|
||||
type: string
|
||||
description: 视频封面链接。
|
||||
request_id:
|
||||
type: string
|
||||
description: 标识此次请求的唯一`ID`，可由用户在客户端请求时提交或平台自动生成。
|
||||
AsyncImageGenerationResponse:
|
||||
type: object
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
description: 模型名称。
|
||||
task_status:
|
||||
type: string
|
||||
description: 任务处理状态，`PROCESSING`（处理中），`SUCCESS`（成功），`FAIL`（失败） 注：处理中状态需通过查询获取结果
|
||||
image_result:
|
||||
type: array
|
||||
description: 数组，包含生成的图片`URL`。
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
url:
|
||||
type: string
|
||||
description: 图片链接。图片的临时链接有效期为`30`天，请及时转存图片。
|
||||
request_id:
|
||||
type: string
|
||||
description: 标识此次请求的唯一`ID`，可由用户在客户端请求时提交或平台自动生成。
|
||||
ChatCompletionChunk:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: 任务 ID
|
||||
created:
|
||||
description: 请求创建时间，`Unix` 时间戳（秒）
|
||||
type: integer
|
||||
model:
|
||||
description: 模型名称
|
||||
type: string
|
||||
choices:
|
||||
type: array
|
||||
description: 模型响应列表
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
index:
|
||||
type: integer
|
||||
description: 结果索引
|
||||
delta:
|
||||
type: object
|
||||
description: 模型增量返回的文本信息
|
||||
properties:
|
||||
role:
|
||||
type: string
|
||||
description: 当前对话的角色，目前默认为 `assistant`（模型）
|
||||
content:
|
||||
oneOf:
|
||||
- type: string
|
||||
description: >-
|
||||
当前对话文本内容。如果调用函数则为 `null`，否则返回推理结果。
|
||||
|
||||
对于`GLM-4.5V`系列模型，返回内容可能包含思考过程标签 `<think>
|
||||
</think>`，文本边界标签 `<|begin_of_box|> <|end_of_box|>`。
|
||||
- type: array
|
||||
description: 当前对话的多模态内容（适用于`GLM-4V`系列）
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
enum:
|
||||
- text
|
||||
description: 内容类型，目前为文本
|
||||
text:
|
||||
type: string
|
||||
description: 文本内容
|
||||
- type: string
|
||||
nullable: true
|
||||
description: 当使用`tool_calls`时，`content`可能为`null`
|
||||
audio:
|
||||
type: object
|
||||
description: 当使用 `glm-4-voice` 模型时返回的音频内容
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: 当前对话的音频内容`id`，可用于多轮对话输入
|
||||
data:
|
||||
type: string
|
||||
description: 当前对话的音频内容`base64`编码
|
||||
expires_at:
|
||||
type: string
|
||||
description: 当前对话的音频内容过期时间
|
||||
reasoning_content:
|
||||
type: string
|
||||
description: 思维链内容, 仅 `glm-4.5` 系列支持
|
||||
tool_calls:
|
||||
type: array
|
||||
description: 生成的应该被调用的工具信息，流式返回时会逐步生成
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
index:
|
||||
type: integer
|
||||
description: 工具调用索引
|
||||
id:
|
||||
type: string
|
||||
description: 工具调用的唯一标识符
|
||||
type:
|
||||
type: string
|
||||
description: 工具类型，目前支持`function`
|
||||
enum:
|
||||
- function
|
||||
function:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
description: 函数名称
|
||||
arguments:
|
||||
type: string
|
||||
description: 函数参数，`JSON`格式字符串
|
||||
finish_reason:
|
||||
type: string
|
||||
description: >-
|
||||
模型推理终止的原因。`stop` 表示自然结束或触发stop词，`tool_calls` 表示模型命中函数，`length`
|
||||
表示达到 `token` 长度限制，`sensitive`
|
||||
表示内容被安全审核接口拦截（用户应判断并决定是否撤回公开内容），`network_error`
|
||||
表示模型推理异常，'model_context_window_exceeded'表示超出模型上下文窗口。
|
||||
enum:
|
||||
- stop
|
||||
- length
|
||||
- tool_calls
|
||||
- sensitive
|
||||
- network_error
|
||||
usage:
|
||||
type: object
|
||||
description: 本次模型调用的 `tokens` 数量统计
|
||||
properties:
|
||||
prompt_tokens:
|
||||
type: integer
|
||||
description: 用户输入的 `tokens` 数量。对于 `glm-4-voice`，`1`秒音频=`12.5 Tokens`，向上取整。
|
||||
completion_tokens:
|
||||
type: integer
|
||||
description: 模型输出的 `tokens` 数量
|
||||
total_tokens:
|
||||
type: integer
|
||||
description: 总 `tokens` 数量，对于 `glm-4-voice` 模型，`1`秒音频=`12.5 Tokens`，向上取整
|
||||
content_filter:
|
||||
type: array
|
||||
description: 返回内容安全的相关信息
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
role:
|
||||
type: string
|
||||
description: >-
|
||||
安全生效环节，包括：`role = assistant` 模型推理，`role = user` 用户输入，`role =
|
||||
history` 历史上下文
|
||||
level:
|
||||
type: integer
|
||||
description: 严重程度 `level 0-3`，`level 0` 表示最严重，`3` 表示轻微
|
||||
Error:
|
||||
type: object
|
||||
properties:
|
||||
error:
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
message:
|
||||
type: string
|
||||
ChatCompletionResponseMessage:
|
||||
type: object
|
||||
properties:
|
||||
role:
|
||||
type: string
|
||||
description: 当前对话角色，默认为 `assistant`
|
||||
example: assistant
|
||||
content:
|
||||
oneOf:
|
||||
- type: string
|
||||
description: >-
|
||||
当前对话文本内容。如果调用函数则为 `null`，否则返回推理结果。
|
||||
|
||||
对于`GLM-4.5V`系列模型，返回内容可能包含思考过程标签 `<think> </think>`，文本边界标签
|
||||
`<|begin_of_box|> <|end_of_box|>`。
|
||||
- type: array
|
||||
description: 多模态回复内容，适用于`GLM-4V`系列模型
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
enum:
|
||||
- text
|
||||
description: 回复内容类型，目前为文本
|
||||
text:
|
||||
type: string
|
||||
description: 文本内容
|
||||
- type: string
|
||||
nullable: true
|
||||
description: 当使用`tool_calls`时，`content`可能为`null`
|
||||
reasoning_content:
|
||||
type: string
|
||||
description: 思维链内容，仅在使用 `glm-4.5` 系列, `glm-4.1v-thinking` 系列模型时返回。
|
||||
audio:
|
||||
type: object
|
||||
description: 当使用 `glm-4-voice` 模型时返回的音频内容
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: 当前对话的音频内容`id`，可用于多轮对话输入
|
||||
data:
|
||||
type: string
|
||||
description: 当前对话的音频内容`base64`编码
|
||||
expires_at:
|
||||
type: string
|
||||
description: 当前对话的音频内容过期时间
|
||||
tool_calls:
|
||||
type: array
|
||||
description: 生成的应该被调用的函数名称和参数。
|
||||
items:
|
||||
$ref: '#/components/schemas/ChatCompletionResponseMessageToolCall'
|
||||
ChatCompletionResponseMessageToolCall:
|
||||
type: object
|
||||
properties:
|
||||
function:
|
||||
type: object
|
||||
description: 包含生成的函数名称和 `JSON` 格式参数。
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
description: 生成的函数名称。
|
||||
arguments:
|
||||
type: string
|
||||
description: 生成的函数调用参数的 `JSON` 格式字符串。调用函数前请验证参数。
|
||||
required:
|
||||
- name
|
||||
- arguments
|
||||
mcp:
|
||||
type: object
|
||||
description: '`MCP` 工具调用参数'
|
||||
properties:
|
||||
id:
|
||||
description: '`mcp` 工具调用唯一标识'
|
||||
type: string
|
||||
type:
|
||||
description: 工具调用类型, 例如 `mcp_list_tools, mcp_call`
|
||||
type: string
|
||||
enum:
|
||||
- mcp_list_tools
|
||||
- mcp_call
|
||||
server_label:
|
||||
description: '`MCP`服务器标签'
|
||||
type: string
|
||||
error:
|
||||
description: 错误信息
|
||||
type: string
|
||||
tools:
|
||||
description: '`type = mcp_list_tools` 时的工具列表'
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
description: 工具名称
|
||||
type: string
|
||||
description:
|
||||
description: 工具描述
|
||||
type: string
|
||||
annotations:
|
||||
description: 工具注解
|
||||
type: object
|
||||
input_schema:
|
||||
description: 工具输入参数规范
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
description: 固定值 'object'
|
||||
type: string
|
||||
default: object
|
||||
enum:
|
||||
- object
|
||||
properties:
|
||||
description: 参数属性定义
|
||||
type: object
|
||||
required:
|
||||
description: 必填属性列表
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
additionalProperties:
|
||||
description: 是否允许额外参数
|
||||
type: boolean
|
||||
arguments:
|
||||
description: 工具调用参数，参数为 `json` 字符串
|
||||
type: string
|
||||
name:
|
||||
description: 工具名称
|
||||
type: string
|
||||
output:
|
||||
description: 工具返回的结果输出
|
||||
type: object
|
||||
id:
|
||||
type: string
|
||||
description: 命中函数的唯一标识符。
|
||||
type:
|
||||
type: string
|
||||
description: 调用的工具类型，目前仅支持 'function', 'mcp'。
|
||||
securitySchemes:
|
||||
bearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
description: >-
|
||||
使用以下格式进行身份验证：Bearer [<your api
|
||||
key>](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
|
||||
|
||||
````
|
||||
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
Reference in new issue
Block a user