seedream_text_to_image

Instructions

Implementation Reference

• seedream_mcp/server.py:106-119 (registration)

  MCP tool registration: decorator registers the tool with name 'seedream_text_to_image', annotations, and handler function that delegates to run_text_to_image.

  @mcp.tool(
      name="seedream_text_to_image",
      annotations=_build_tool_annotations("Seedream 文生图", GENERATION_TOOL_ANNOTATIONS),
  )
  async def seedream_text_to_image(
      params: TextToImageInput,
      ctx: Context[Any, Any, Any],
  ) -> CallToolResult:
      """
      文生图：
  
      通过给模型提供清晰准确的文字指令，即可快速获得符合描述的高质量单张图片。
      """
      return await run_text_to_image(params, config=_get_active_config(), ctx=ctx)

• seedream_mcp/tools/impl/text_to_image.py:32-101 (handler)

  Core business logic handler for text-to-image. Builds the execution context, calls client.text_to_image API, and delegates to the generic execute_generation_handler pipeline.

  async def handle_text_to_image(
      arguments: Dict[str, Any],
      config: SeedreamConfig,
      ctx: "Context[Any, Any, Any] | None" = None,
  ) -> CallToolResult:
      """
      处理文生图请求
  
      根据用户提供的文本提示词生成图片，支持尺寸配置、水印添加、提示词优化及自动保存等功能。
      调用 API 生成图片后，可选择性地将结果保存至本地并返回统一格式的响应。
  
      Args:
          arguments: 请求参数字典,包含以下键值：
              - prompt (str): 生成图片的文本提示词
              - optimize_prompt_options (dict, optional): 提示词优化选项配置
              - size (str, optional): 图片尺寸规格
              - watermark (bool, optional): 是否添加水印
              - response_format (str, optional): 响应格式，"url" 或 "b64_json"，默认为 "url"
              - output_format (str, optional): 输出图片格式，仅 Seedream 5.0 支持 "jpeg" 或 "png"
              - stream (bool, optional): 是否启用流式输出，默认为 False
              - tools (list, optional): 模型工具配置，仅 Seedream 5.0 支持，如 [{"type": "web_search"}]
              - request_count (int, optional): 并行请求次数，默认 1，范围 1-4
              - parallelism (int, optional): 并行度上限，默认 min(request_count, 4)，范围 1-4
              - auto_save (bool, optional): 是否自动保存生成的图片
              - save_path (str, optional): 自定义图片保存路径
              - custom_name (str, optional): 自定义文件名前缀
  
      Returns:
          CallToolResult: MCP 标准工具结果。
              - content: 面向模型的文本摘要
              - structuredContent: 结构化结果数据
              - isError: 是否为错误结果
      """
  
      async def _execute(
          client: "SeedreamClient", context: GenerationExecutionContext
      ) -> Dict[str, Any]:
          result = await client.text_to_image(
              prompt=context.prompt,
              optimize_prompt_options=context.optimize_prompt_options,
              size=context.size,
              watermark=context.watermark,
              response_format=context.response_format,
              output_format=context.output_format,
              stream=context.stream,
              tools=context.tools,
          )
          return cast(Dict[str, Any], result)
  
      return await execute_generation_handler(
          arguments=arguments,
          config=config,
          module_logger=logger,
          tool_name="text_to_image",
          completion_title="文生图任务完成",
          failure_prefix="文生图生成",
          guidance="请检查提示词长度、尺寸与模型兼容性，确认 API Key 和网络可用后重试。",
          start_log_message=(
              "文生图开始: prompt_len={}, size={}, stream={}, request_count={}, parallelism={}"
          ),
          start_log_values_builder=lambda ctx: (
              len(ctx.prompt or ""),
              ctx.size,
              ctx.stream,
              ctx.request_count,
              ctx.parallelism,
          ),
          request_executor=_execute,
          ctx=ctx,
      )

• seedream_mcp/tools/core/runners.py:26-45 (helper)

  Runner/adapter that converts validated Pydantic params (TextToImageInput) to a dict and delegates to handle_text_to_image handler.

  async def run_text_to_image(
      params: TextToImageInput,
      config: SeedreamConfig,
      ctx: Context | None = None,
  ) -> CallToolResult:
      """
      执行文生图生成工具
  
      Args:
          params: 文生图生成的已验证参数对象。
  
      Returns:
          MCP 结构化工具结果。
      """
      async with workspace_roots_scope(ctx):
          return await handle_text_to_image(
              params.model_dump(exclude_none=True),
              config=config,
              ctx=ctx,
          )

• seedream_mcp/tools/core/schemas.py:275-289 (schema)

  Pydantic input schema for text-to-image tool, combining response/execution, size/watermark, and prompt/optimize field groups.

  class TextToImageInput(
      BaseGenerationInput,
      _ResponseAndExecutionInput,
      _SizeAndWatermarkInput,
      _PromptAndOptimizeInput,
  ):
      """
      文生图：通过提供清晰准确的文字指令，即可快速获得符合描述的高质量单张图片。
      """
  
      prompt: str = Field(
          ...,
          min_length=1,
          description="用于生成图片的提示词，建议不超过300个汉字或600个英文单词。",
      )