Send Completion Message
Available for: Text Generator apps.
Sends a request to a text-generation app and returns the generated text.
curl --request POST \
--url https://{api_base_url}/completion-messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"inputs": {
"city": "New York"
},
"query": "Summarize the following text: ...",
"response_mode": "blocking",
"user": "def-456"
}
'{
"answer": "Hello World!...",
"created_at": 1705407629,
"event": "message",
"id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e",
"message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
"metadata": {
"usage": {
"completion_price": "0.0002560",
"completion_price_unit": "0.001",
"completion_tokens": 128,
"completion_unit_price": "0.002",
"currency": "USD",
"latency": 0.7682376249867957,
"prompt_price": "0.0010330",
"prompt_price_unit": "0.001",
"prompt_tokens": 1033,
"prompt_unit_price": "0.001",
"total_price": "0.0012890",
"total_tokens": 1161
}
},
"mode": "completion",
"task_id": "c3800678-a077-43df-a102-53f23ed20b88"
}Authorizations
Every request authenticates with an API key: Authorization: Bearer {API_KEY}. App endpoints take an app API key; knowledge endpoints take a knowledge base API key (Get Started).
Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).
Body
Request body to create a completion message.
Values for the app's input variables, keyed by variable name. The expected names and types come from the user_input_form field of Get App Parameters.
When a file or file-list input is omitted or null, the app uses the default configured for that input.
End-user identifier, defined by your app and unique within it. Messages and files are visible only to requests carrying the same user. See End User Identity.
Files to attach to the request. For a local file, first upload it via Upload File, then reference the returned id as upload_file_id with transfer_method: local_file.
- Option 1
- Option 2
Show child attributes
Show child attributes
Mode of response return. Defaults to blocking when omitted.
streaming(recommended): the reply arrives as Server-Sent Events.blocking: returns once generation completes. Long generations risk interruption: on Dify Cloud, the edge proxy may end the connection if the response doesn't arrive within its timeout.
streaming, blocking Response
Successful response. The content type and structure depend on the response_mode parameter in the request.
- If
response_modeisblocking, returnsapplication/jsonwith aCompletionResponseobject. - If
response_modeisstreaming, returnstext/event-streamwith a stream ofChunkCompletionEventobjects.
Task ID for request tracking and the Stop Completion Message Generation API.
Was this page helpful?
curl --request POST \
--url https://{api_base_url}/completion-messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"inputs": {
"city": "New York"
},
"query": "Summarize the following text: ...",
"response_mode": "blocking",
"user": "def-456"
}
'{
"answer": "Hello World!...",
"created_at": 1705407629,
"event": "message",
"id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e",
"message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
"metadata": {
"usage": {
"completion_price": "0.0002560",
"completion_price_unit": "0.001",
"completion_tokens": 128,
"completion_unit_price": "0.002",
"currency": "USD",
"latency": 0.7682376249867957,
"prompt_price": "0.0010330",
"prompt_price_unit": "0.001",
"prompt_tokens": 1033,
"prompt_unit_price": "0.001",
"total_price": "0.0012890",
"total_tokens": 1161
}
},
"mode": "completion",
"task_id": "c3800678-a077-43df-a102-53f23ed20b88"
}