Skip to content

Commit cdb0236

Browse files
v-regandownerv-regandowner
authored
Merge pull request #265410 from mrbullwinkle/mrb_02_06_2024_ref_updates
[Azure OpenAI] [Assistants Reference]
2 parents fece035 + 8b31e9c commit cdb0236

File tree

6 files changed

+1732
-0
lines changed

6 files changed

+1732
-0
lines changed

‎articles/ai-services/openai/assistants-reference-messages.md

Lines changed: 388 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,388 @@
1+
---
2+
title: Azure OpenAI Service Assistants Python & REST API messages reference
3+
titleSuffix: Azure OpenAI
4+
description: Learn how to use Azure OpenAI's Python & REST API messages with Assistants.
5+
manager: nitinme
6+
ms.service: azure-ai-openai
7+
ms.topic: conceptual
8+
ms.date: 02/01/2024
9+
author: mrbullwinkle
10+
ms.author: mbullwin
11+
recommendations: false
12+
ms.custom:
13+
---
14+
15+
# Assistants API (Preview) messages reference
16+
17+
This article provides reference documentation for Python and REST for the new Assistants API (Preview). More in-depth step-by-step guidance is provided in the [getting started guide](./how-to/assistant.md).
18+
19+
## Create message
20+
21+
```http
22+
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages?api-version=2024-02-15-preview
23+
```
24+
25+
Create a message.
26+
27+
**Path parameter**
28+
29+
|Parameter| Type | Required | Description |
30+
|---|---|---|---|
31+
|`thread_id` | string | Required | The ID of the thread to create a message for. |
32+
33+
**Request body**
34+
35+
|Name | Type | Required | Description |
36+
|--- |--- |--- |--- |
37+
| `role` | string | Required | The role of the entity that is creating the message. Currently only user is supported.|
38+
| `content` | string | Required | The content of the message. |
39+
| `file_ids` | array | Optional | A list of File IDs that the message should use. There can be a maximum of 10 files attached to a message. Useful for tools like retrieval and code_interpreter that can access and use files. |
40+
| `metadata` | map | Optional | Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maximum of 512 characters long. |
41+
42+
### Returns
43+
44+
A [message](#message-object) object.
45+
46+
### Example create message request
47+
48+
# [Python 1.x](#tab/python)
49+
50+
```python
51+
from openai import AzureOpenAI
52+
53+
client = AzureOpenAI(
54+
api_key=os.getenv("AZURE_OPENAI_KEY"),
55+
api_version="2024-02-15-preview",
56+
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
57+
)
58+
59+
thread_message = client.beta.threads.messages.create(
60+
"thread_abc123",
61+
role="user",
62+
content="How does AI work? Explain it in simple terms.",
63+
)
64+
print(thread_message)
65+
```
66+
67+
# [REST](#tab/rest)
68+
69+
```console
70+
curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages?api-version=2024-02-15-preview \
71+
-H "api-key: $AZURE_OPENAI_KEY" \
72+
-H 'Content-Type: application/json' \
73+
-d '{
74+
"role": "user",
75+
"content": "How does AI work? Explain it in simple terms."
76+
}'
77+
```
78+
79+
---
80+
81+
## List messages
82+
83+
```http
84+
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages?api-version=2024-02-15-preview
85+
```
86+
87+
Returns a list of messages for a given thread.
88+
89+
**Path Parameters**
90+
91+
92+
|Parameter| Type | Required | Description |
93+
|---|---|---|---|
94+
|`thread_id` | string | Required | The ID of the thread that messages belong to. |
95+
96+
**Query Parameters**
97+
98+
|Name | Type | Required | Description |
99+
|--- |--- |--- |--- |
100+
| `limit` | integer | Optional - Defaults to 20 |A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.|
101+
| `order` | string | Optional - Defaults to desc |Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.|
102+
| `after` | string | Optional | A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.|
103+
| `before` | string | Optional | A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.|
104+
105+
### Returns
106+
107+
A list of [message](#message-object) objects.
108+
109+
### Example list messages request
110+
111+
# [Python 1.x](#tab/python)
112+
113+
```python
114+
from openai import AzureOpenAI
115+
116+
client = AzureOpenAI(
117+
api_key=os.getenv("AZURE_OPENAI_KEY"),
118+
api_version="2024-02-15-preview",
119+
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
120+
)
121+
122+
thread_messages = client.beta.threads.messages.list("thread_abc123")
123+
print(thread_messages.data)
124+
125+
```
126+
127+
# [REST](#tab/rest)
128+
129+
```console
130+
curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages?api-version=2024-02-15-preview \
131+
-H "api-key: $AZURE_OPENAI_KEY" \
132+
-H 'Content-Type: application/json'
133+
```
134+
135+
---
136+
137+
## List message files
138+
139+
```http
140+
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}/files?api-version=2024-02-15-preview
141+
```
142+
143+
Returns a list of message files.
144+
145+
|Parameter| Type | Required | Description |
146+
|---|---|---|---|
147+
|`thread_id` | string | Required | The ID of the thread that the message and files belong to. |
148+
|`message_id`| string | Required | The ID of the message that the files belongs to. |
149+
150+
**Query Parameters**
151+
152+
|Name | Type | Required | Description |
153+
|--- |--- |--- |--- |
154+
| `limit` | integer | Optional - Defaults to 20 |A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.|
155+
| `order` | string | Optional - Defaults to desc |Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.|
156+
| `after` | string | Optional | A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.|
157+
| `before` | string | Optional | A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.|
158+
159+
### Returns
160+
161+
A list of [message file](#message-file-object) objects
162+
163+
### Example list message files request
164+
165+
# [Python 1.x](#tab/python)
166+
167+
```python
168+
from openai import AzureOpenAI
169+
170+
client = AzureOpenAI(
171+
api_key=os.getenv("AZURE_OPENAI_KEY"),
172+
api_version="2024-02-15-preview",
173+
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
174+
)
175+
176+
message_files = client.beta.threads.messages.files.list(
177+
thread_id="thread_abc123",
178+
message_id="msg_abc123"
179+
)
180+
print(message_files)
181+
182+
```
183+
184+
# [REST](#tab/rest)
185+
186+
```console
187+
curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/files?api-version=2024-02-15-preview \
188+
-H "api-key: $AZURE_OPENAI_KEY" \
189+
-H 'Content-Type: application/json'
190+
```
191+
192+
---
193+
194+
## Retrieve message
195+
196+
```http
197+
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-02-15-preview
198+
```
199+
200+
Retrieves a message file.
201+
202+
**Path parameters**
203+
204+
|Parameter| Type | Required | Description |
205+
|---|---|---|---|
206+
|`thread_id` | string | Required | The ID of the thread that the message belongs to. |
207+
|`message_id`| string | Required | The ID of the message to retrieve. |
208+
209+
210+
### Returns
211+
212+
The [message](#message-object) object matching the specified ID.
213+
214+
### Example retrieve message request
215+
216+
# [Python 1.x](#tab/python)
217+
218+
```python
219+
from openai import AzureOpenAI
220+
221+
client = AzureOpenAI(
222+
api_key=os.getenv("AZURE_OPENAI_KEY"),
223+
api_version="2024-02-15-preview",
224+
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
225+
)
226+
227+
message = client.beta.threads.messages.retrieve(
228+
message_id="msg_abc123",
229+
thread_id="thread_abc123",
230+
)
231+
print(message)
232+
233+
```
234+
235+
# [REST](#tab/rest)
236+
237+
```console
238+
curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-02-15-preview \
239+
-H "api-key: $AZURE_OPENAI_KEY" \
240+
-H 'Content-Type: application/json'
241+
```
242+
243+
---
244+
245+
## Retrieve message file
246+
247+
```http
248+
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}/files/{file_id}?api-version=2024-02-15-preview
249+
```
250+
251+
Retrieves a message file.
252+
253+
**Path parameters**
254+
255+
|Parameter| Type | Required | Description |
256+
|---|---|---|---|
257+
|`thread_id` | string | Required | The ID of the thread, which the message and file belongs to. |
258+
|`message_id`| string | Required | The ID of the message that the file belongs to. |
259+
|`file_id` | string | Required | The ID of the file being retrieved. |
260+
261+
**Returns**
262+
263+
The [message file](#message-file-object) object.
264+
265+
### Example retrieve message file request
266+
267+
# [Python 1.x](#tab/python)
268+
269+
```python
270+
from openai import AzureOpenAI
271+
272+
client = AzureOpenAI(
273+
api_key=os.getenv("AZURE_OPENAI_KEY"),
274+
api_version="2024-02-15-preview",
275+
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
276+
)
277+
278+
message_files = client.beta.threads.messages.files.retrieve(
279+
thread_id="thread_abc123",
280+
message_id="msg_abc123",
281+
file_id="assistant-abc123"
282+
)
283+
print(message_files)
284+
```
285+
286+
# [REST](#tab/rest)
287+
288+
```console
289+
curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}/files/{file_id}?api-version=2024-02-15-preview
290+
``` \
291+
-H "api-key: $AZURE_OPENAI_KEY" \
292+
-H 'Content-Type: application/json'
293+
```
294+
295+
---
296+
297+
## Modify message
298+
299+
```http
300+
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-02-15-preview
301+
```
302+
303+
Modifies a message.
304+
305+
**Path parameters**
306+
307+
|Parameter| Type | Required | Description |
308+
|---|---|---|---|
309+
|`thread_id` | string | Required | The ID of the thread to which the message belongs. |
310+
|`message_id`| string | Required | The ID of the message to modify. |
311+
312+
**Request body**
313+
314+
|Parameter| Type | Required | Description |
315+
|---|---|---|---|
316+
| metadata | map| Optional | Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maximum of 512 characters long.|
317+
318+
### Returns
319+
320+
The modified [message](#message-object) object.
321+
322+
# [Python 1.x](#tab/python)
323+
324+
```python
325+
from openai import AzureOpenAI
326+
327+
client = AzureOpenAI(
328+
api_key=os.getenv("AZURE_OPENAI_KEY"),
329+
api_version="2024-02-15-preview",
330+
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
331+
)
332+
333+
message = client.beta.threads.messages.update(
334+
message_id="msg_abc12",
335+
thread_id="thread_abc123",
336+
metadata={
337+
"modified": "true",
338+
"user": "abc123",
339+
},
340+
)
341+
print(message)
342+
```
343+
344+
# [REST](#tab/rest)
345+
346+
```console
347+
curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-02-15-preview
348+
``` \
349+
-H "api-key: $AZURE_OPENAI_KEY" \
350+
-H 'Content-Type: application/json' \
351+
-d '{
352+
"metadata": {
353+
"modified": "true",
354+
"user": "abc123"
355+
}
356+
}'
357+
358+
```
359+
360+
---
361+
362+
## Message object
363+
364+
Represents a message within a thread.
365+
366+
|Name | Type | Description |
367+
|--- |--- |--- |
368+
| `id` | string |The identifier, which can be referenced in API endpoints.|
369+
| `object` | string |The object type, which is always thread.message.|
370+
| `created_at` | integer |The Unix timestamp (in seconds) for when the message was created.|
371+
| `thread_id` | string |The thread ID that this message belongs to.|
372+
| `role` | string |The entity that produced the message. One of user or assistant.|
373+
| `content` | array |The content of the message in array of text and/or images.|
374+
| `assistant_id` | string or null |If applicable, the ID of the assistant that authored this message.|
375+
| `run_id` | string or null |If applicable, the ID of the run associated with the authoring of this message.|
376+
| `file_ids` | array |A list of file IDs that the assistant should use. Useful for tools like retrieval and code_interpreter that can access files. A maximum of 10 files can be attached to a message.|
377+
| `metadata` | map |Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maximum of 512 characters long.|
378+
379+
## Message file object
380+
381+
A list of files attached to a message.
382+
383+
|Name | Type | Description |
384+
|--- |--- |--- |
385+
| `id`| string | The identifier, which can be referenced in API endpoints.|
386+
|`object`|string| The object type, which is always `thread.message.file`.|
387+
|`created_at`|integer | The Unix timestamp (in seconds) for when the message file was created.|
388+
|`message_id`| string | The ID of the message that the File is attached to.|

0 commit comments

Comments
 (0)