transform_image

Instructions

Implementation Reference

• src/yaparai/tools/edit.py:10-55 (handler)

  Handler function that executes the transform_image tool logic. Calls YaparAIClient.generate() with 'img2img' mode and YaparAIClient.wait_for_result() to produce the result.

  async def transform_image(
      prompt: str,
      image_url: str,
      negative_prompt: str = "",
      width: int = 512,
      height: int = 512,
      style: Literal["realistic", "anime", "cinematic", "artistic"] | None = None,
  ) -> dict:
      """
      Transform an existing image using AI (image-to-image).
  
      Uses the source image as a reference and applies the prompt to create
      a new variation. Great for style transfer, modifications, and enhancements.
      Cost: ~6 credits.
  
      Args:
          prompt: Description of the desired transformation
          image_url: URL of the source image to transform
          negative_prompt: Things to avoid in the output
          width: Output width in pixels (64-2048, default 512)
          height: Output height in pixels (64-2048, default 512)
          style: Style preset (realistic, anime, cinematic, artistic)
  
      Returns:
          Dict with image_url, job_id, credits_used, and balance_remaining.
      """
      client = YaparAIClient()
      job = await client.generate({
          "type": "image",
          "mode": "img2img",
          "prompt": prompt,
          "negative_prompt": negative_prompt,
          "image_url": image_url,
          "width": width,
          "height": height,
          "style": style,
      })
  
      result = await client.wait_for_result(job["job_id"], timeout=60)
      return {
          "status": "success",
          "image_url": result.get("result_url"),
          "job_id": result.get("job_id"),
          "credits_used": job.get("credits_used"),
          "balance_remaining": job.get("balance_remaining"),
      }

• src/yaparai/server.py:129-129 (registration)

  Registration of transform_image as an MCP tool via FastMCP's @tool decorator (using mcp.tool()).

  mcp.tool(transform_image)

• src/yaparai/client.py:126-128 (helper)

  YaparAIClient.generate() is the HTTP helper that sends the image-to-image request payload to the API.

  async def generate(self, request: dict) -> dict:
      """Start a generation job."""
      return await self._request("POST", "/v1/public/generate", json=request)

• src/yaparai/client.py:142-163 (helper)

  YaparAIClient.wait_for_result() polls the job status until completion; used by transform_image to get the final result.

  async def wait_for_result(
      self,
      job_id: str,
      timeout: int = 120,
      poll_interval: int = 3,
  ) -> dict:
      """Poll job status until completed or timeout."""
      elapsed = 0
      while elapsed < timeout:
          job = await self.get_job(job_id)
          status = job.get("status", "")
          if status == "succeeded":
              return job
          if status == "failed":
              error = job.get("error_message") or job.get("error") or "Unknown error"
              raise RuntimeError(f"Generation failed: {error}")
          await asyncio.sleep(poll_interval)
          elapsed += poll_interval
      raise TimeoutError(
          f"Job {job_id} is still processing after {timeout}s. "
          f"Use get_job_status('{job_id}') to check later."
      )