# ToAPIs 图像生成 API 参考（当前 skill 默认）

## 当前默认配置

```bash
GEMINI_BASE_URL=https://toapis.com
GEMINI_API_KEY=<REDACTED>
GEMINI_OPENAI_TIMEOUT_SECONDS=900
```

> 默认调试模型：`gpt-4o-image`  
> 原因：按 `$HOME/Downloads/文字生图的模型配置价格单.png`，这是这次选定的最低成本 GPT-4o 图片调试模型。

---

## 1. 创建图片生成任务

### 端点

```http
POST https://toapis.com/v1/images/generations
```

### 请求头

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

### GPT-4o 默认调试示例

```json
{
  "model": "gpt-4o-image",
  "prompt": "赛博朋克风格的城市夜景，霓虹灯闪烁",
  "size": "16:9",
  "n": 1
}
```

### Gemini Flash 示例

```json
{
  "model": "gemini-3.1-flash-image-preview",
  "prompt": "赛博朋克风格的城市夜景，霓虹灯闪烁",
  "size": "16:9",
  "n": 1,
  "metadata": {
    "resolution": "2K"
  }
}
```

### curl 示例

```bash
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-4o-image",
    "prompt": "赛博朋克风格的城市夜景，霓虹灯闪烁",
    "size": "16:9",
    "n": 1
  }'
```

### 典型响应

```json
{
  "id": "task_xxx",
  "object": "generation.task",
  "model": "gpt-4o-image",
  "status": "queued",
  "progress": 0,
  "created_at": 1775458392
}
```

---

## 2. 轮询图片任务状态

### 端点

```http
GET https://toapis.com/v1/images/generations/{task_id}
```

### curl 示例

```bash
curl --request GET \
  --url https://toapis.com/v1/images/generations/task_xxx \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

### 完成态示例

```json
{
  "id": "task_xxx",
  "object": "generation.task",
  "model": "gpt-4o-image",
  "status": "completed",
  "progress": 100,
  "result": {
    "type": "image",
    "data": [
      {
        "url": "https://files.toapis.com/images/...png"
      }
    ]
  }
}
```

---

## 3. 上传本地参考图

当本地有 `--input reference.png` 时，当前脚本会先上传图片，再把上传后的 URL 塞进生成任务。

### 端点

```http
POST https://toapis.com/v1/uploads/images
```

### curl 示例

```bash
curl --request POST \
  --url https://toapis.com/v1/uploads/images \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --form 'file=@reference.png'
```

### 当前脚本的后续请求格式

```json
{
  "model": "gpt-4o-image",
  "prompt": "把它改成赛博朋克风格，但保留主体构图",
  "size": "1:1",
  "n": 1,
  "image_urls": [
    "https://files.toapis.com/uploads/reference.png"
  ]
}
```

---

## 4. 当前脚本的实际策略

文件：

```bash
$HOME/.claude/skills/gemini-image-api/scripts/gemini_generate.py
```

行为：

1. 若 `base_url` 是 `https://toapis.com`
   - 走官方异步任务接口
   - 有本地输入图就先上传
   - 轮询状态直到完成
   - 下载最终图片
2. 若 `base_url` 不是 ToAPIs
   - 保留旧的 native `/v1beta` + `/v1` fallback 兼容逻辑

---

## 5. 模型与成本建议

| 模型 | 用途 | 成本策略 |
|------|------|----------|
| `gpt-4o-image` | 默认调试 | **最低成本优先** |
| `gemini-3.1-flash-image-preview` | 便宜 Gemini 调试 | 次优先 |
| `gemini-3-pro-image-preview` | 最终高质量出图 | 仅必要时 |

---

## 6. 与 Git 安全相关的处理

真实 `.env`：

```bash
$HOME/.claude/skills/gemini-image-api/.env
```

现在已经配套：

- `.env.example`：可提交
- `.env`：本地保留
- `$HOME/.claude/.gitignore`：忽略 `skills/**/.env`

这样后续不会再把真实 API Key 误提交进 Git。
