Dify Octri Demo
POST/completion-messages

Send Completion Message

Available for: Text Generator apps.

Sends a request to a text-generation app and returns the generated text.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

5 body fields

Request body to create a completion message.

filesarray<object>optional
Files to attach to the request. For a local file, first upload it via [Upload File](/en/api-reference/files/upload-file), then reference the returned `id` as `upload_file_id` with `transfer_method: local_file`.
inputsobjectrequired
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](/en/api-reference/applications/get-app-parameters).
querystringoptional
The text to process. Legacy field; newer apps pass this inside `inputs` instead.
Default:
response_modestringoptional
Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes). Cloudflare timeout is `100 s`. When omitted, defaults to blocking behavior.
Allowed:streamingblocking
userstringrequired
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](/en/api-reference/guides/end-user-identity).

4 status codes
200Successful 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.
answerstringoptional
Complete response content.
created_atintegeroptional
Message creation timestamp (Unix epoch seconds).
eventstringoptional
Event type, fixed as `message`.
idstringoptional
Unique ID of this response event.
message_idstringoptional
Unique message ID. Use this as the `message_id` parameter when calling feedback or suggested questions endpoints.
metadataobjectoptional
Metadata including usage and retriever resources.
modestringoptional
App mode, fixed as `completion`.
task_idstringoptional
Task ID for request tracking and the [Stop Completion Message Generation](/en/api-reference/completion-messages/stop-completion-message-generation) API.
400- `app_unavailable` : App unavailable or misconfigured. - `provider_not_initialize` : No valid model provider credentials found. - `provider_quota_exceeded` : Model provider quota exhausted. - `model_currently_not_support` : Current model unavailable. - `completion_request_error` : Text generation failed. - `invalid_param` : The required `user` field is missing.

6 documented failures

  • app_unavailable

    App unavailable, please check your app configurations.

    app_unavailable

  • completion_request_error

    Completion request failed.

    completion_request_error

  • invalid_param

    Arg user must be provided.

    invalid_param

  • model_currently_not_support

    Dify Hosted OpenAI trial currently not support the GPT-4 model.

    model_currently_not_support

  • provider_not_initialize

    No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.

    provider_not_initialize

  • provider_quota_exceeded

    Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.

    provider_quota_exceeded

429`too_many_requests` : Too many concurrent requests for this app.

One documented failure

  • too_many_requests

    Too many requests. Please try again later. The current maximum concurrent requests allowed for 5b3d4f2a-1c9e-4a7b-8f6d-2e0c9a1b3d4f is 10.

    too_many_requests

500`internal_server_error` : Internal server error.

One documented failure

  • internal_server_error

    The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application.

    internal_server_error

Error handling

A 400 is returned: - app_unavailable : App unavailable or misconfigured.

  • provider_not_initialize : No valid model provider credentials found.
  • provider_quota_exceeded : Model provider quota exhausted.
  • model_currently_not_support : Current model unavailable.
  • completion_request_error : Text generation failed.
  • invalid_param : The required user field is missing. A 429 is returned: too_many_requests : Too many concurrent requests for this app. A 500 is returned: internal_server_error : Internal server error.