microsoft/semantic-kernel · error · ServiceResponseException

Failed to edit image: {ex}

Error message

Failed to edit image: {ex}

What it means

Raised as ServiceResponseException in _send_image_edit_request when any exception occurs during client.images.edit. This endpoint accepts image files (and optionally a mask) plus generation settings; failures include invalid file formats, file-size limits, content-filter rejections, or API/network errors.

Source

Thrown at python/semantic_kernel/connectors/ai/open_ai/services/open_ai_handler.py:159

        Args:
            image: List of image files to edit. Accepts file paths or bytes.
            settings: Image edit execution settings.
            mask: Optional mask image. Accepts file path or bytes.

        Returns:
            ImagesResponse: The response from the image edit API.
        """
        try:
            response: ImagesResponse = await self.client.images.edit(
                image=image,
                mask=mask,  # type: ignore
                **settings.prepare_settings_dict(),
            )
            self.store_usage(response)
            return response
        except Exception as ex:
            raise ServiceResponseException(f"Failed to edit image: {ex}") from ex

    async def _send_audio_to_text_request(self, settings: OpenAIAudioToTextExecutionSettings) -> Transcription:
        """Send a request to the OpenAI audio to text endpoint."""
        if not settings.filename:
            raise ServiceInvalidRequestError("Audio file is required for audio to text service")

        try:
            with open(settings.filename, "rb") as audio_file:
                return await self.client.audio.transcriptions.create(
                    file=audio_file,
                    **settings.prepare_settings_dict(),
                )
        except Exception as ex:
            raise ServiceResponseException(
                f"{type(self)} service failed to transcribe audio",
                ex,
            ) from ex

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Inspect the interpolated exception message for the specific API error reason
2. Verify image files are valid PNG and within size limits (max 4MB per OpenAI spec)
3. Ensure the mask, if provided, has the same dimensions as the image and uses alpha channel transparency
4. For content-filter rejections, rephrase the editing prompt

Example fix

# before
response = await service._send_image_edit_request(image=[b'corrupt_data'], settings=settings)
# after — validate file before sending
from pathlib import Path
img_bytes = Path('input.png').read_bytes()
if len(img_bytes) > 4 * 1024 * 1024:
    raise ValueError('Image exceeds 4MB limit')
response = await service._send_image_edit_request(image=[img_bytes], settings=settings)

MAX_FILE_SIZE = 4 * 1024 * 1024  # 4MB
for f in image_files:
    data = f if isinstance(f, bytes) else Path(f).read_bytes()
    if len(data) > MAX_FILE_SIZE:
        raise ValueError(f'Image file exceeds {MAX_FILE_SIZE} bytes')
    if not data[:8].startswith(b'\\x89PNG'):
        logger.warning('Image may not be a valid PNG')

from semantic_kernel.exceptions import ServiceResponseException

try:
    response = await service._send_image_edit_request(image=img, settings=settings, mask=mask)
except ServiceResponseException as e:
    logger.error('Image edit failed: %s', e)
    raise

When it happens

Trigger: Calling image edit with invalid image files (wrong format, too large, corrupt), missing or invalid mask, unsupported parameters for the edit endpoint, or network/quota failures during client.images.edit.

Common situations: Passing PNG when a different format is required; file exceeding the 4MB limit; mask not matching the image dimensions; using dall-e-2-specific parameters with an unsupported model; content filter on the edit prompt.

Related errors

• Failed to generate image: {ex}
• {type(self)} service failed to generate embeddings
• {type(self)} service failed to transcribe audio
• {type(self)} service failed to generate audio
• Provide either 'image_paths' or 'image_files', and only one.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/370459b9d7f56375. Report an issue: GitHub.