# 图片生成大模型集成基本信息
* 集成 ID: integration-doubao-seedream
* 显示名称: 图片生成大模型
* 集成类型: 内置集成

# 集成描述
这是一个用于 Python 的多模态视频生成模型使用说明。它使用火山方舟视频生成的调用方式，调用的时候需要向用户申请获取火山API密钥。
此集成是调用生图模型，非大语言模型（llm），仅用于图像生成。

重要提示：
| API Base URL | `https://ark.cn-beijing.volces.com/api/v3/` |
| API Endpoint | `POST /images/generations` |
| 认证方式 | Bearer Token (ARK_API_KEY) |
| 接口类型 | 同步接口 (支持流式输出) |
| 图片保留 | URL 有效期 24 小时 |

* api_key 需要主动向用户获取火山引擎 ARK_API_KEY，请在调用前提示用户提供。
* 支持的 API: /images/generations（图片生成）
* 支持以下模型:
   * doubao-seedream-4-5-251128
      * 总像素取值范围：[2560x1440, 4096x4096]

# 使用说明
请参阅以下说明、代码片段和文档 URL（如有），了解如何使用此集成
* 针对常见错误实现重试或告警机制, 处理各种异常情况，并记录错误详情，便于问题排查。
* 图片生成耗时较长，若需要多个 prompt 批量生成，请尽量使用**异步模式**并行调用。
```python
# Example：将代码示例中的函数 image_generation 改为异步调用模式
import asyncio

async def image_generation():
    ...

async def image_generation_async_example():
    prompts = [...]
    # 批量创建任务（并发执行）
    tasks = [image_generation(prompt=prompt, ...) for prompt in prompts]
    results = await asyncio.gather(*tasks)  # 等待所有任务完成
    
    for res in results:
        ...
```

### 代码示例
提供的函数入参已经完备，请**禁止**创造出不存在的入参。
```python
from typing import Union, Optional
from cozeloop.decorator import observe
from coze_coding_utils.runtime_ctx.context  import Context, default_headers
from utils.file.file import File
import requests

# API Base URL（固定值）
API_BASE_URL = "https://ark.cn-beijing.volces.com/api/v3"


@observe
def image_generation(
        ctx: Context,
        prompt: str,
        ark_api_key: str,
        size: Optional[str] = "2K",
        watermark: Optional[bool] = True,
        image: Optional[Union[str, list[str]]] = None,
        response_format: Optional[str] = "url",
        optimize_prompt_mode: Optional[str] = "standard",
        sequential_image_generation: Optional[str] = "disabled",
        sequential_image_generation_max_images: Optional[int] = 15,
) -> tuple[list[File], dict]:
    """
    图片生成函数，用于根据文本描述生成图片。调用生图模型，非大语言模型，仅用于生成图片

    Args:
        ctx: 上下文对象，用于串联一次运行态的相关信息
        prompt: 用于生成图像的提示词，支持中英文。建议不超过300个汉字或600个英文单词。字数过多信息容易分散，模型可能因此忽略细节，只关注重点，造成图片缺失部分元素。
        ark_api_key: 火山引擎 ARK API 密钥，需要主动向用户获取。
        size: 生成图片的尺寸，可指定生成图像的分辨率，可选值："2K"、"4K"，默认为"2K"
              也可指定生成图像的宽高像素值，格式为"宽度x高度"，如"2560x1440"。
        watermark: 是否在生成的图片上添加水印，默认为True
        image: 输入的图片信息，支持 URL 或 Base64 编码。当提供参考图片时，生成的图片会参考其风格或内容。最多支持传入 14 张参考图。
               URL：请确保图片URL可被访问。
               Base64编码：请遵循此格式`data:image/<图片格式>;base64,<Base64编码>`。注意`<图片格式>`需小写，如`data:image/png;base64,<base64_image>`
               传入图片需要满足以下条件：
               * 图片格式：jpeg、png、webp、bmp、tiff、gif
               * 宽高比（宽/高）范围：
                    * [1/16, 16] (适用模型：doubao-seedream-4.5、doubao-seedream-4.0）
               * 宽高长度（px） > 14
               * 大小：不超过 10MB
               * 总像素：不超过 6000×6000 px
        response_format: 指定生成图像的返回格式，可选值为"url"或"b64_json"，默认为"url"
                        "url"返回图片URL，"b64_json"返回Base64编码的图片数据
        optimize_prompt_mode: 提示词优化模式，可选值为"standard"、"fast"，默认为"standard"
                              standard：标准模式，生成内容的质量更高，耗时较长。
                              fast：快速模式，生成内容的耗时更短，质量一般。
        sequential_image_generation: 控制是否关闭组图功能，可选值为"auto"或"disabled"，默认为"disabled"
                                     auto：自动判断模式，模型会根据用户提供的提示词自主判断是否返回组图以及组图包含的图片数量。
                                     disabled：关闭组图功能，模型只会生成一张图。
        sequential_image_generation_max_images: 生成的最大图片数量，仅当sequential_image_generation为"auto"时生效，¬取值范围为1-20，默认为15

    Returns:
        包含两个元素的元组
        - 第一个元素是图片文件列表，包含生成的图片URL或Base64编码数据
        - 第二个元素是完整的API响应数据，成功响应示例：
        {
            "model": "doubao-seedream-4-5-251128",
            "created": 1757321139,
            "data": [
                {
                    "url": "https://...",
                    "size": "3104x1312"
                    "b64_json": "..."
                    "error": {
                        "message": "...",
                        "code": "..."
                    }
                }
            ],
            "usage": {
                "generated_images": 1,
                "output_tokens": xxx,
                "total_tokens": xxx
            },
            "error": {
                "message": "...",
                "code": "..."
            }
        }
    """
    # 检查 API 密钥
    if not ark_api_key:
        raise ValueError("请提供火山引擎 ARK API 密钥（ark_api_key）")
    
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {ark_api_key}",
    }
    headers.update(default_headers(ctx))
    request = {
        "model": "doubao-seedream-4-5-251128",
        "prompt": prompt,
        "size": size,
        "watermark": watermark,
        "image": image,
        "response_format": response_format,
        "optimize_prompt_options": {
            "mode": optimize_prompt_mode,
        },
        "sequential_image_generation": sequential_image_generation,
        "sequential_image_generation_options": {
            "max_images": sequential_image_generation_max_images,
        },
    }
    try:
        response = requests.post(f'{API_BASE_URL}/images/generations', json=request, headers=headers)

        data = response.json()
        if "error" in data:
            raise Exception(
                f"图片生成失败: code={data.get('error', {}).get('code')}, message={data.get('error', {}).get('message')}")
        response.raise_for_status()

        img_list = []
        for item in data["data"]:
            if "url" in item:
                img_list.append(File(url=item["url"], file_type="image"))
            elif "b64_json" in item:
                img_list.append(item["b64_json"])
            elif "error" in item:
                raise Exception(
                    f"图片生成失败: code={item.get('error', {}).get('code')}, message={item.get('error', {}).get('message')}")
        return img_list, data
    except requests.exceptions.RequestException as e:
        raise Exception(f"网络请求失败: {e}")
    except Exception as e:
        raise Exception(f"图片生成失败: {e}")
    finally:
        response.close()
```