Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

feat: add vision support for OpenAI chat conversion (#1061)

Fethi Amari1b4c7e6779c1
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index fd228e4c..5a785ee0 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -631,7 +631,7 @@ usage quirks such as DeepSeek prompt-cache counters.
content/tool/thinking blocks, and Anthropic response envelopes;
- trace-safe request snapshots stay beside those models so the generic trace
module remains protocol-independent and import-order safe;
-- content and message conversion for OpenAI-compatible upstreams;
+- text, image, and message conversion for OpenAI-compatible upstreams;
- request serialization primitives shared by provider request policies;
- tool schema and tool-result handling;
- thinking block handling;
@@ -639,6 +639,13 @@ usage quirks such as DeepSeek prompt-cache counters.
stream ledger, Anthropic SSE emitter, continuation-body construction, and tool repair;
- token counting and Anthropic-owned failure-kind-to-wire mapping.
+User image conversion is a pure protocol operation. Core maps Anthropic base64
+and URL image sources to ordered OpenAI `image_url` content parts without
+fetching remote content. Provider adapters do not gate that conversion behind a
+provider-wide vision flag; the selected upstream model owns image capability,
+while any deliberate provider-specific attachment removal remains explicit
+compatibility policy.
+
Shared stream behavior lives under
[src/free_claude_code/core/anthropic/streaming/](src/free_claude_code/core/anthropic/streaming/). The shared layer owns the
Anthropic content-block ledger, SSE serialization, continuation request
diff --git a/README.md b/README.md
index 65b7e315..1aa56aa7 100644
--- a/README.md
+++ b/README.md
@@ -58,7 +58,7 @@ Run your coding agents with free, paid, or local models. Choose and validate pro
- Switch among 24 cloud and local providers from the Admin UI.
- Use each coding agent's native model picker.
- Route Opus, Sonnet, Haiku, and fallback traffic to different models.
-- Keep streaming, tool use, and reasoning support across compatible models.
+- Keep streaming, tool use, reasoning, and image input across compatible models.
- Connect Claude Code and Codex in VS Code or Claude Code through JetBrains ACP.
- Optionally run Claude Code sessions through Discord or Telegram with voice-note transcription.
- Protect the local proxy with optional token authentication.
diff --git a/pyproject.toml b/pyproject.toml
index 72c39050..45131281 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "4.1.0"
+version = "4.2.0"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/src/free_claude_code/core/anthropic/conversion.py b/src/free_claude_code/core/anthropic/conversion.py
index 53ad699f..b58c4c49 100644
--- a/src/free_claude_code/core/anthropic/conversion.py
+++ b/src/free_claude_code/core/anthropic/conversion.py
@@ -146,6 +146,33 @@ def _assert_no_forbidden_assistant_block(block: Any) -> None:
)
+def _openai_user_image_part(block: Any) -> dict[str, Any]:
+ """Convert one Anthropic user image block without performing I/O."""
+ source = get_block_attr(block, "source", {})
+ source_type = get_block_attr(source, "type")
+
+ if source_type == "base64":
+ media_type = get_block_attr(source, "media_type")
+ if not isinstance(media_type, str) or not media_type.strip():
+ raise OpenAIConversionError(
+ "Base64 image source requires a non-empty media_type."
+ )
+ data = get_block_attr(source, "data")
+ if not isinstance(data, str) or not data.strip():
+ raise OpenAIConversionError("Base64 image source requires non-empty data.")
+ url = f"data:{media_type};base64,{data}"
+ elif source_type == "url":
+ url = get_block_attr(source, "url")
+ if not isinstance(url, str) or not url.strip():
+ raise OpenAIConversionError("URL image source requires a non-empty url.")
+ else:
+ raise OpenAIConversionError(
+ f"Unsupported image source type {source_type!r}; expected 'base64' or 'url'."
+ )
+
+ return {"type": "image_url", "image_url": {"url": url}}
+
+
class _OpenAIChatHistoryLedger:
"""Assemble OpenAI chat history while respecting tool-result dependencies."""
@@ -482,25 +509,31 @@ class AnthropicToOpenAIConverter:
@staticmethod
def _convert_user_message(content: list[Any]) -> list[dict[str, Any]]:
result: list[dict[str, Any]] = []
- text_parts: list[str] = []
-
- def flush_text() -> None:
- if text_parts:
- result.append({"role": "user", "content": "\n".join(text_parts)})
- text_parts.clear()
+ content_parts: list[dict[str, Any]] = []
+
+ def flush_content() -> None:
+ if not content_parts:
+ return
+ if all(part["type"] == "text" for part in content_parts):
+ message_content: str | list[dict[str, Any]] = "\n".join(
+ part["text"] for part in content_parts
+ )
+ else:
+ message_content = list(content_parts)
+ result.append({"role": "user", "content": message_content})
+ content_parts.clear()
for block in content:
block_type = get_block_type(block)
if block_type == "text":
- text_parts.append(get_block_attr(block, "text", ""))
- elif block_type == "image":
- raise OpenAIConversionError(
- "User message image blocks are not supported for OpenAI chat "
- "conversion; remove the image blocks or extend the converter."
+ content_parts.append(
+ {"type": "text", "text": get_block_attr(block, "text", "")}
)
+ elif block_type == "image":
+ content_parts.append(_openai_user_image_part(block))
elif block_type == "tool_result":
- flush_text()
+ flush_content()
tool_content = get_block_attr(block, "content", "")
serialized = serialize_tool_result_content(tool_content)
result.append(
@@ -511,7 +544,7 @@ class AnthropicToOpenAIConverter:
}
)
- flush_text()
+ flush_content()
return result
@staticmethod
diff --git a/tests/providers/test_converter.py b/tests/providers/test_converter.py
index ed656caa..ffb1b662 100644
--- a/tests/providers/test_converter.py
+++ b/tests/providers/test_converter.py
@@ -698,12 +698,131 @@ def test_assistant_redacted_thinking_omitted_from_openai_chat():
assert "reasoning_content" not in result[0]
-def test_convert_user_message_image_raises():
- content = [
- MockBlock(type="image", source={"type": "url", "url": "https://example.com/x"})
+ "source,expected_url",
+ [
+ (
+ {"type": "base64", "media_type": "image/png", "data": "AAAA"},
+ "data:image/png;base64,AAAA",
+ ),
+ (
+ {"type": "url", "url": "https://example.com/image.png"},
+ "https://example.com/image.png",
+ ),
+ ],
+)
+def test_convert_user_message_image_sources(source, expected_url):
+ messages = [MockMessage("user", [MockBlock(type="image", source=source)])]
+
+ result = AnthropicToOpenAIConverter.convert_messages(messages)
+
+ assert result == [
+ {
+ "role": "user",
+ "content": [{"type": "image_url", "image_url": {"url": expected_url}}],
+ }
]
- messages = [MockMessage("user", content)]
- with pytest.raises(OpenAIConversionError):
+
+
+def test_convert_user_message_preserves_interleaved_image_text_order():
+ messages = [
+ MockMessage(
+ "user",
+ [
+ MockBlock(
+ type="image",
+ source={
+ "type": "base64",
+ "media_type": "image/jpeg",
+ "data": "FIRST",
+ },
+ ),
+ MockBlock(type="text", text="Compare the first image with this one."),
+ MockBlock(
+ type="image",
+ source={"type": "url", "url": "https://example.com/second.jpg"},
+ ),
+ MockBlock(type="text", text="Describe the differences."),
+ ],
+ )
+ ]
+
+ result = AnthropicToOpenAIConverter.convert_messages(messages)
+
+ assert result == [
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "image_url",
+ "image_url": {"url": "data:image/jpeg;base64,FIRST"},
+ },
+ {
+ "type": "text",
+ "text": "Compare the first image with this one.",
+ },
+ {
+ "type": "image_url",
+ "image_url": {"url": "https://example.com/second.jpg"},
+ },
+ {"type": "text", "text": "Describe the differences."},
+ ],
+ }
+ ]
+
+
+def test_convert_user_image_before_tool_result_preserves_message_order():
+ messages = [
+ MockMessage(
+ "user",
+ [
+ MockBlock(type="text", text="Inspect this."),
+ MockBlock(
+ type="image",
+ source={"type": "url", "url": "https://example.com/image.png"},
+ ),
+ MockBlock(type="tool_result", tool_use_id="tool_1", content="done"),
+ ],
+ )
+ ]
+
+ result = AnthropicToOpenAIConverter.convert_messages(messages)
+
+ assert result == [
+ {
+ "role": "user",
+ "content": [
+ {"type": "text", "text": "Inspect this."},
+ {
+ "type": "image_url",
+ "image_url": {"url": "https://example.com/image.png"},
+ },
+ ],
+ },
+ {"role": "tool", "tool_call_id": "tool_1", "content": "done"},
+ ]
+
+
+ "source,error",
+ [
+ (
+ {"type": "base64", "media_type": "", "data": "AAAA"},
+ "non-empty media_type",
+ ),
+ (
+ {"type": "base64", "media_type": "image/png", "data": ""},
+ "non-empty data",
+ ),
+ ({"type": "url", "url": ""}, "non-empty url"),
+ ({"type": "file", "file_id": "file_1"}, "Unsupported image source type"),
+ ({}, "Unsupported image source type"),
+ ],
+)
+def test_convert_user_message_rejects_unconvertible_image_sources(source, error):
+ messages = [MockMessage("user", [MockBlock(type="image", source=source)])]
+
+ with pytest.raises(OpenAIConversionError, match=error):
AnthropicToOpenAIConverter.convert_messages(messages)
@@ -1013,6 +1132,45 @@ def test_openai_build_accepts_declared_native_top_level_hints() -> None:
assert body["model"] == "m"
+def test_openai_build_converts_validated_anthropic_image_block() -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "vision-model",
+ "messages": [
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "image",
+ "source": {
+ "type": "base64",
+ "media_type": "image/webp",
+ "data": "AAAA",
+ },
+ },
+ {"type": "text", "text": "What is shown?"},
+ ],
+ }
+ ],
+ }
+ )
+
+ body = build_base_request_body(request)
+
+ assert body["messages"] == [
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "image_url",
+ "image_url": {"url": "data:image/webp;base64,AAAA"},
+ },
+ {"type": "text", "text": "What is shown?"},
+ ],
+ }
+ ]
+
+
def test_openai_build_rejects_unknown_top_level_extras() -> None:
"""Truly unknown keys must still be rejected (not dropped silently)."""
req = MessagesRequest.model_validate(
diff --git a/uv.lock b/uv.lock
index 09d4bf53..eb2f7a53 100644
--- a/uv.lock
+++ b/uv.lock
@@ -561,7 +561,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "4.1.0"
+version = "4.2.0"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },