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.mdindex 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 tracemodule 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 theAnthropic content-block ledger, SSE serialization, continuation requestdiff --git a/README.md b/README.mdindex 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.tomlindex 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.pyindex 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:@staticmethoddef _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@staticmethoddiff --git a/tests/providers/test_converter.py b/tests/providers/test_converter.pyindex 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.lockindex 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" },