Skip to content

Commit 4bf35ec

Browse files
ericc-chericc-ch
committed
docs: Update mapping doc with latest API details and features
1 parent 6fb9c85 commit 4bf35ec

File tree

2 files changed

+157
-82
lines changed

2 files changed

+157
-82
lines changed

‎docs/mapping.md‎

Lines changed: 62 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,23 @@
1-
Of course. Here is the updated and corrected mapping document, now including the "Models" and "Token Count" endpoints.
2-
3-
---
4-
51
### **Comprehensive API Translation: Anthropic Messages & OpenAI Chat Completions**
62

7-
This document provides a detailed, side-by-side technical mapping of the Anthropic Messages API and the OpenAI Chat Completions API, based on the provided API specifications.
3+
This document provides a detailed, side-by-side technical mapping of the Anthropic Messages API and the OpenAI Chat Completions API, verified against their respective specifications.
84

95
---
106

11-
### **1. API Endpoints & Authentication**
7+
### **1. Endpoints & Authentication**
128

13-
| Feature | Anthropic Messages API | OpenAI Chat Completions API |
14-
| :-------------- | :------------------------ | :----------------------------------- |
15-
| **Endpoint** | `POST /v1/messages` | `POST /v1/chat/completions` |
16-
| **Auth Header** | `x-api-key: YOUR_API_KEY` | `Authorization: Bearer YOUR_API_KEY` |
9+
| Feature | Anthropic Messages API | OpenAI Chat Completions API |
10+
| :------------------- | :------------------------ | :----------------------------------- |
11+
| **Primary Endpoint** | `POST /v1/messages` | `POST /v1/chat/completions` |
12+
| **Auth Header** | `x-api-key: YOUR_API_KEY` | `Authorization: Bearer YOUR_API_KEY` |
1713

1814
---
1915

2016
### **2. Core Request Parameters**
2117

22-
| Parameter | Anthropic Messages API | OpenAI Chat Completions API |
18+
This table outlines the translation of primary request body fields.
19+
20+
| Parameter | Anthropic Messages API (`claude.md`) | OpenAI Chat Completions API (`openapi.documented.yml`) |
2321
| :------------------ | :------------------------------------------- | :------------------------------------------------------------------ |
2422
| **Model** | `model` (e.g., `claude-3-7-sonnet-20250219`) | `model` (e.g., `gpt-4o`) |
2523
| **System Prompt** | `system` (A top-level string) | Prepending a message with `role: "system"` to the `messages` array. |
@@ -48,72 +46,88 @@ Both APIs use a `messages` array, but the structure and content types differ.
4846

4947
#### **3.2. Message Content Types**
5048

51-
| Content Type | Anthropic Messages API | OpenAI Chat Completions API |
52-
| :-------------- | :----------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
53-
| **Text** | `content` can be a single string or an array containing `{"type": "text", "text": "..."}`. | A message object's `content` property is a string, or an array containing `{"type": "text", "text": "..."}`. |
54-
| **Image** | `content` array can contain `{"type": "image", "source": {"type": "base64", "media_type": "...", "data": "..."}}`. | `content` array can contain `{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}`. |
55-
| **Tool Result** | A `user` message `content` array can contain `{"type": "tool_result", "tool_use_id": "...", "content": "..."}`. | A distinct message object with `{"role": "tool", "tool_call_id": "...", "content": "..."}`. |
49+
| Content Type | Anthropic Messages API (`claude.md`) | OpenAI Chat Completions API (`openapi.documented.yml`) |
50+
| :-------------- | :----------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- |
51+
| **Text** | `content` can be a single string or an array with `{"type": "text", "text": "..."}`. | A message object's `content` is a string or an array with `{"type": "text", "text": "..."}`. |
52+
| **Image** | `content` array can contain `{"type": "image", "source": {"type": "base64", "media_type": "...", "data": "..."}}`. | `content` array can contain `{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}`. |
53+
| **Tool Result** | A `user` message `content` array can contain `{"type": "tool_result", "tool_use_id": "...", "content": "..."}`. | A distinct message object: `{"role": "tool", "tool_call_id": "...", "content": "..."}`. |
5654

5755
---
5856

5957
### **4. Tool & Function Handling**
6058

61-
| Feature | Anthropic Messages API | OpenAI Chat Completions API |
62-
| :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
63-
| **Tool Definition** | `tools` array. Each tool has `name`, `description`, and `input_schema`. | `tools` array. Each tool has `type: "function"` and a `function` object with `name`, `description`, and `parameters` (JSON Schema). |
64-
| **Tool Choice** | `tool_choice` object with `type`: \<br\> - `"auto"`: Model decides. \<br\> - `"any"`: Forces model to use a tool. \<br\> - `"tool"`: Forces a specific tool. | `tool_choice` string or object: \<br\> - `"auto"`: Model decides. \<br\> - `"required"`: Forces model to call a tool. \<br\> - `{"type": "function", ...}`: Forces a specific function. |
65-
| **Tool Call in Response** | Appears in the `content` array as `{"type": "tool_use", "id": "...", "name": "...", "input": {...}}`. | Appears in the `message` object as a `tool_calls` array, with each call having an `id` and a `function` object with `name` and `arguments` (as a JSON string). |
59+
| Feature | Anthropic Messages API (`claude.md`) | OpenAI Chat Completions API (`openapi.documented.yml`) |
60+
| :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
61+
| **Tool Definition** | `tools` array. Each tool has `name`, `description`, and `input_schema`. | `tools` array. Each tool has `type: "function"` and a `function` object with `name`, `description`, and `parameters`. |
62+
| **Tool Choice** | `tool_choice` object with `type`: \<br\> - `"auto"` \<br\> - `"any"` (Forces use of a tool) \<br\> - `"tool"` (Forces specific tool) | `tool_choice` string or object: \<br\> - `"auto"` \<br\> - `"required"` (Forces use of a tool) \<br\> - `{"type": "function", ...}` (Forces specific function) |
63+
| **Tool Call in Response** | In `content` array as `{"type": "tool_use", "id": "...", "name": "...", "input": {...}}`. | In `message` object as a `tool_calls` array, with `id` and `function` object (`name`, `arguments` as JSON string). |
6664

6765
---
6866

6967
### **5. Response Structure**
7068

71-
| Feature | Anthropic Messages API | OpenAI Chat Completions API |
72-
| :------------------- | :----------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
73-
| **Primary Object** | A single response object. | A `choices` array containing one or more message objects. |
74-
| **Stop Reason** | `stop_reason` field with values like `end_turn`, `max_tokens`, `tool_use`, `stop_sequence`, `refusal`. | `finish_reason` field within each choice, with values like `stop`, `length`, `tool_calls`, `content_filter`. |
75-
| **Usage Statistics** | `usage` object with `input_tokens` and `output_tokens`. | `usage` object with `prompt_tokens`, `completion_tokens`, and `total_tokens`. |
69+
| Feature | Anthropic Messages API (`claude.md`) | OpenAI Chat Completions API (`openapi.documented.yml`) |
70+
| :------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- |
71+
| **Primary Object** | A single response object. | A `choices` array containing one or more message objects. |
72+
| **Stop Reason** | `stop_reason` field. Values: `end_turn`, `max_tokens`, `tool_use`, `stop_sequence`, `refusal`. | `finish_reason` field. Values: `stop`, `length`, `tool_calls`, `content_filter`. |
73+
| **Usage Statistics** | `usage` object with `input_tokens` and `output_tokens`. | `usage` object with `prompt_tokens`, `completion_tokens`, and `total_tokens`. |
7674

7775
---
7876

7977
### **6. Model & Tokenization Endpoints**
8078

8179
#### **6.1. List Available Models**
8280

83-
| Feature | Anthropic Messages API | OpenAI Chat Completions API |
84-
| :---------------- | :------------------------------------------ | :------------------------------------- |
85-
| **Endpoint** | `GET /v1/models` | `GET /v1/models` |
86-
| **Response** | Paginated list in `data` array. | List in `data` array. |
87-
| **Object Fields** | `id`, `display_name`, `created_at`, `type`. | `id`, `created`, `owned_by`, `object`. |
81+
| Feature | Anthropic Messages API | OpenAI Chat Completions API |
82+
| :---------------- | :--------------------------------- | :-------------------------- |
83+
| **Endpoint** | `GET /v1/models` | `GET /v1/models` |
84+
| **Response** | Paginated list in `data` array. | List in `data` array. |
85+
| **Object Fields** | `id`, `display_name`, `created_at` | `id`, `created`, `owned_by` |
8886

8987
#### **6.2. Retrieve a Specific Model**
9088

91-
| Feature | Anthropic Messages API | OpenAI Chat Completions API |
92-
| :---------------- | :------------------------------------------ | :------------------------------------- |
93-
| **Endpoint** | `GET /v1/models/{model_id}` | `GET /v1/models/{model}` |
94-
| **Response** | A single `ModelInfo` object. | A single `Model` object. |
95-
| **Object Fields** | `id`, `display_name`, `created_at`, `type`. | `id`, `created`, `owned_by`, `object`. |
89+
| Feature | Anthropic Messages API | OpenAI Chat Completions API |
90+
| :----------- | :--------------------------- | :-------------------------- |
91+
| **Endpoint** | `GET /v1/models/{model_id}` | `GET /v1/models/{model}` |
92+
| **Response** | A single `ModelInfo` object. | A single `Model` object. |
9693

9794
#### **6.3. Count Tokens**
9895

99-
| Feature | Anthropic Messages API | OpenAI Chat Completions API |
100-
| :---------------- | :------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
101-
| **Endpoint** | `POST /v1/messages/count_tokens` | **No Direct API Endpoint** |
102-
| **Functionality** | Counts tokens for a given message payload, including images and tools, without generating a completion. | Token counts are returned in the `usage` object only after a completion is generated. Client-side libraries like `tiktoken` must be used for estimation. |
103-
| **Response** | `{"input_tokens": ...}` | N/A |
96+
| Feature | Anthropic Messages API | OpenAI Chat Completions API |
97+
| :---------------- | :----------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
98+
| **Endpoint** | `POST /v1/messages/count_tokens` | **No Direct API Endpoint** |
99+
| **Functionality** | Counts tokens for a message payload (including images and tools) before making a full completion call. | Token counts are returned in the `usage` object only _after_ a completion is generated. Client-side libraries (e.g., `tiktoken`) must be used for pre-calculation. |
100+
| **Response** | `{"input_tokens": ...}` | N/A |
104101

105102
---
106103

107-
### **7. Streaming & Error Handling**
104+
### **7. Streaming**
105+
106+
Both APIs support streaming via Server-Sent Events (SSE), but the event structure is fundamentally different.
107+
108+
- **Anthropic:** Emits a sequence of distinct, named events such as `message_start`, `content_block_start`, `content_block_delta`, and `message_stop`. This provides a highly structured stream.
109+
- **OpenAI:** Emits a series of unnamed `data:` events containing `chat.completion.chunk` objects with partial updates. The stream terminates with `data: [DONE]`.
110+
111+
A translation layer must buffer OpenAI's delta chunks to reconstruct Anthropic's structured event stream, including generating necessary IDs and calculating token usage for the final event.
112+
113+
---
114+
115+
### **8. Error Handling**
116+
117+
Error responses are structurally similar, containing a main `error` object. HTTP status codes generally correspond.
108118

109-
- **Streaming:** Both APIs use Server-Sent Events (SSE). A translation layer must convert OpenAI's stream of `chat.completion.chunk` objects into Anthropic's more granular, named-event stream (`message_start`, `content_block_delta`, etc.).
110-
- **Error Handling:** Error responses are structurally similar, containing a main `error` object. HTTP status codes generally correspond (e.g., 400 for bad requests, 401 for auth issues, 429 for rate limits).
119+
| HTTP Code | Anthropic `error.type` | OpenAI `error.type` |
120+
| :-------- | :---------------------- | :------------------------ |
121+
| 400 | `invalid_request_error` | `invalid_request_error` |
122+
| 401 | `authentication_error` | `authentication_error` |
123+
| 403 | `permission_error` | `permission_denied_error` |
124+
| 429 | `rate_limit_error` | `rate_limit_error` |
125+
| 500 | `api_error` | `internal_server_error` |
111126

112127
---
113128

114-
### **8. Summary of Key Differences**
129+
### **9. Summary of Key Asymmetrical Features**
115130

116-
- **Token Counting:** Anthropic provides a dedicated API endpoint for counting tokens before sending a request, while OpenAI does not.
117-
- **`top_k`:** Supported by Anthropic for request sampling, but not by OpenAI's Chat Completions API.
118-
- **Model Information:** The APIs return different metadata for their models. Anthropic provides a `display_name`, whereas OpenAI provides `owned_by`.
131+
- **`top_k` Sampling:** Supported by Anthropic, but not by OpenAI's Chat Completions API.
119132
- **Partial Assistant Prefill:** Anthropic allows providing a prefix for the assistant's response, a feature OpenAI does not support.
133+
- **Dedicated Token Counting:** Anthropic offers a specific API endpoint to count tokens before a call, whereas OpenAI does not.

0 commit comments

Comments
 (0)