Send Completion Message

curl --request POST \ --url https://{api_base_url}/completion-messages \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data @- <<EOF { "inputs": { "city": "San Francisco" }, "query": "Translate 'hello' to Spanish.", "response_mode": "streaming", "user": "abc-123", "files": [ { "type": "image", "transfer_method": "remote_url", "url": "https://cloud.dify.ai/logo/logo-site.png" } ] } EOF

{ "event": "message", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", "mode": "completion", "answer": "Hello World!...", "metadata": { "usage": { "prompt_tokens": 1033, "prompt_unit_price": "0.001", "prompt_price_unit": "0.001", "prompt_price": "0.0010330", "completion_tokens": 128, "completion_unit_price": "0.002", "completion_price_unit": "0.001", "completion_price": "0.0002560", "total_tokens": 1161, "total_price": "0.0012890", "currency": "USD", "latency": 0.7682376249867957 } }, "created_at": 1705407629 }

Authorizations

Authorization

string

header

required

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

application/json

Request body to create a completion message.

inputs

object

required

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.

user

string

required

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.

query

string

default:""

The text to process. Legacy field; newer apps pass this inside inputs instead.

response_mode

enum<string>

Response mode. Defaults to blocking when omitted.

streaming (recommended): returns the response as Server-Sent Events.
blocking: returns after generation completes.

For long generations, use streaming, or make sure your reverse proxy or gateway timeout exceeds the longest generation.

Available options:

streaming,

blocking

files

object[]

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

Response

Successful response. The content type and structure depend on the response_mode parameter in the request.

If response_mode is blocking, returns application/json with a CompletionResponse object.
If response_mode is streaming, returns text/event-stream with a stream of ChunkCompletionEvent objects.

event

string

Event type, fixed as message.

task_id

string<uuid>

Task ID for request tracking and the Stop Completion Message Generation API.

string<uuid>

Unique ID of this response event.

message_id

string<uuid>

Unique message ID. Use this as the message_id parameter when calling feedback or suggested questions endpoints.

mode

string

App mode, fixed as completion.

answer

string

Complete response content.

metadata

object

Metadata including usage and retriever resources.

Show child attributes

created_at

integer<int64>

Message creation timestamp (Unix epoch seconds).

Guides

App APIs

Knowledge APIs

Authorizations

Body

Response