# see2ai_image_generation_alternative_v1

> SEE2AI 图像生成备用通道，支持文字出图和参考图改图。适合在主通道繁忙时保持稳定出图，并为多素材创作提供补充能力。

## 📖 接入指引

**Endpoint**: `POST /api/v1/actions/see2ai_image_generation_alternative_v1`

**认证方式**: Bearer Token (租户 API Key)

### Endpoints

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/api/v1/actions/see2ai_image_generation_alternative_v1` | Submit the standard action request. |
| `POST` | `/api/v1/actions/see2ai_image_generation_alternative_v1/async` | Submit an asynchronous image job. Returns `task_id` and initial `status`. |
| `GET` | `/api/v1/actions/see2ai_image_generation_alternative_v1/status/{task_id}` | Poll the image job. When completed, read final images from `result_urls`. |

### Async Result Flow

1. Submit the generation request and save the returned `task_id`.
2. Poll `GET /api/v1/actions/see2ai_image_generation_alternative_v1/status/{task_id}` with the same API key until the task reaches a terminal status.
3. Read the final artifact URL from the status response. Use `image_url` for UniWorld and `result_urls` for image/video actions.

> **⚠️ 重要提示**
> 
> 本 API 是 SEE2AI 平台标准化封装后的接口，**参数格式与任何上游 API 不同**。
> 请直接使用下方 Schema 中定义的参数，无需参考其他文档。
> 
> *例如：*
> *- 文本模型参数可能是 `query` 而不是 `messages` 数组*
> *- 视频模型参数可能是 `brief` (创意简报) 而不是复杂的配置项*

## 📥 输入参数 (Input Schema)

```json
{
  "description": "Input schema for SEE2AI image generation.",
  "properties": {
    "prompt": {
      "description": "目标图像的文字说明。",
      "maxLength": 32000,
      "title": "Prompt",
      "type": "string"
    },
    "image_input": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "description": "可选公网参考图片 URL。提供后用于基于参考图改图；不提供时按文字说明直接生成图片。",
      "title": "Image Input"
    },
    "size": {
      "default": "1024x1024",
      "description": "期望输出尺寸，支持预设尺寸或有效的 WIDTHxHEIGHT 自定义尺寸。",
      "title": "Size",
      "type": "string"
    },
    "quality": {
      "default": "auto",
      "description": "期望输出质量。",
      "enum": [
        "auto",
        "high",
        "medium",
        "low"
      ],
      "title": "Quality",
      "type": "string"
    },
    "background": {
      "default": "auto",
      "description": "期望背景模式。当前通道不支持透明背景，前置校验会拦截。",
      "enum": [
        "auto",
        "opaque",
        "transparent"
      ],
      "title": "Background",
      "type": "string"
    },
    "moderation": {
      "default": "auto",
      "description": "内容安全审核强度。",
      "enum": [
        "auto",
        "low"
      ],
      "title": "Moderation",
      "type": "string"
    },
    "output_format": {
      "default": "auto",
      "description": "期望输出格式。",
      "enum": [
        "auto",
        "png",
        "jpeg",
        "webp"
      ],
      "title": "Output Format",
      "type": "string"
    },
    "output_compression": {
      "default": 100,
      "description": "jpeg 或 webp 输出的压缩等级。",
      "title": "Output Compression",
      "type": "integer"
    },
    "n": {
      "default": 1,
      "description": "生成图片数量。当前标准动作每个异步任务仅支持 1 张图片。",
      "title": "N",
      "type": "integer"
    },
    "user": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "可选终端用户标识，用于平台风控审计。",
      "title": "User"
    }
  },
  "required": [
    "prompt"
  ],
  "title": "ImageGenerationInput",
  "type": "object"
}
```

### 参数说明

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `prompt` | string | ✅ 是 | `-` | 目标图像的文字说明。 |
| `image_input` | array / null | ❌ 否 | `-` | 可选公网参考图片 URL。提供后用于基于参考图改图；不提供时按文字说明直接生成图片。 |
| `size` | string | ❌ 否 | `1024x1024` | 期望输出尺寸，支持预设尺寸或有效的 WIDTHxHEIGHT 自定义尺寸。 |
| `quality` | string enum | ❌ 否 | `auto` | 期望输出质量。 |
| `background` | string enum | ❌ 否 | `auto` | 期望背景模式。当前通道不支持透明背景，前置校验会拦截。 |
| `moderation` | string enum | ❌ 否 | `auto` | 内容安全审核强度。 |
| `output_format` | string enum | ❌ 否 | `auto` | 期望输出格式。 |
| `output_compression` | integer | ❌ 否 | `100` | jpeg 或 webp 输出的压缩等级。 |
| `n` | integer | ❌ 否 | `1` | 生成图片数量。当前标准动作每个异步任务仅支持 1 张图片。 |
| `user` | string / null | ❌ 否 | `-` | 可选终端用户标识，用于平台风控审计。 |

## 📤 输出结果 (Output Schema)

```json
{
  "description": "Output schema for SEE2AI image generation.",
  "properties": {
    "input_tokens": {
      "default": 0,
      "description": "输入消耗的词元数量",
      "title": "Input Tokens",
      "type": "integer"
    },
    "output_tokens": {
      "default": 0,
      "description": "输出消耗的词元数量",
      "title": "Output Tokens",
      "type": "integer"
    },
    "total_tokens": {
      "default": 0,
      "description": "总消耗的词元数量",
      "title": "Total Tokens",
      "type": "integer"
    },
    "model": {
      "default": "",
      "description": "实际使用的 SEE2AI 化身模型名称（由各 action 显式填写）",
      "title": "Model",
      "type": "string"
    },
    "source": {
      "default": "see2ai",
      "description": "服务来源（统一 `see2ai`；真实路由仅平台内部可见）",
      "title": "Source",
      "type": "string"
    },
    "cost_points": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "预先计算的扣费词元（如果插件内部已经计算好费用，则直接使用此值，忽略基于词元的计算）",
      "title": "Cost Points"
    },
    "result_urls": {
      "description": "SEE2AI 托管的结果 URL 列表。",
      "items": {
        "type": "string"
      },
      "title": "Result Urls",
      "type": "array"
    },
    "task_id": {
      "description": "生成任务 ID。",
      "title": "Task Id",
      "type": "string"
    },
    "cost_time": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "生成耗时，单位毫秒。",
      "title": "Cost Time"
    },
    "state": {
      "description": "任务最终状态。",
      "title": "State",
      "type": "string"
    },
    "provider_config_id": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "内部配置 ID，用于平台审计。",
      "title": "Provider Config Id"
    },
    "warnings": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "前置校验器返回的非阻断优化建议。",
      "title": "Warnings"
    }
  },
  "required": [
    "task_id",
    "state"
  ],
  "title": "ImageGenerationOutput",
  "type": "object"
}
```

### 输出字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `input_tokens` | integer | 输入消耗的词元数量 |
| `output_tokens` | integer | 输出消耗的词元数量 |
| `total_tokens` | integer | 总消耗的词元数量 |
| `model` | string | 实际使用的 SEE2AI 化身模型名称（由各 action 显式填写） |
| `source` | string | 服务来源（统一 `see2ai`；真实路由仅平台内部可见） |
| `cost_points` | integer / null | 预先计算的扣费词元（如果插件内部已经计算好费用，则直接使用此值，忽略基于词元的计算） |
| `result_urls` | array | SEE2AI 托管的结果 URL 列表。 |
| `task_id` | string | 生成任务 ID。 |
| `cost_time` | integer / null | 生成耗时，单位毫秒。 |
| `state` | string | 任务最终状态。 |
| `provider_config_id` | integer / null | 内部配置 ID，用于平台审计。 |
| `warnings` | array / null | 前置校验器返回的非阻断优化建议。 |

## 💡 调用示例

### cURL 示例

```bash
curl -X POST "https://see2ai.com/api/v1/actions/see2ai_image_generation_alternative_v1" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer sk-your-tenant-api-key" \
     -d '{
  "prompt": "Create a clean product visual with clear composition.",
  "size": "1024x1024",
  "quality": "auto",
  "background": "auto",
  "moderation": "auto",
  "output_format": "auto",
  "output_compression": 100,
  "n": 1
}'
```

### Python 示例

```python
import requests

API_KEY = "sk-your-tenant-api-key"
ENDPOINT = "https://see2ai.com/api/v1/actions/see2ai_image_generation_alternative_v1"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

payload = {
  "prompt": "Create a clean product visual with clear composition.",
  "size": "1024x1024",
  "quality": "auto",
  "background": "auto",
  "moderation": "auto",
  "output_format": "auto",
  "output_compression": 100,
  "n": 1
}

response = requests.post(ENDPOINT, json=payload, headers=headers)
result = response.json()

print(f"结果：{result}")
```

## 💰 计费说明

> Usage-based billing using SEE2AI image input/output token accounting.

**注意**: 所有费用都以词元为单位，系统会自动从租户余额中扣除。

## ⚠️ 常见错误码

| HTTP 状态码 | 错误原因 | 解决方案 |
| --- | --- | --- |
| `400` | Validation failed before upstream generation started | 请稍后重试 |
| `401` | Invalid or unauthorized provider API key | 检查 API Key 是否正确，或联系管理员充值 |
| `402` | Insufficient balance | 请稍后重试 |
| `429` | Rate limit exceeded | 降低请求频率，或联系管理员调整限流配置 |
| `500` | Upstream image generation or hosting failed | 稍后重试，如持续失败请联系技术支持 |

## 📞 技术支持

- **文档问题**: 查看 [SEE2AI 官方文档](https://see2ai.com/docs)
- **API 状态**: 访问 [服务状态页面](https://see2ai.com/status)
- **问题反馈**: 联系技术支持团队

---

**API 版本**: see2ai_image_generation_alternative_v1
**最后更新**: 2026-03-23