> ## Documentation Index > Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # Send Completion Message > **Available for**: Text Generator apps. Sends a request to a text-generation app and returns the generated text. ## OpenAPI ````yaml /en/3.11.x/develop/api/openapi_service.json post /completion-messages openapi: 3.0.1 info: title: Dify Service API description: >- REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key. version: 1.0.0 servers: - url: https://{api_base_url} description: >- Base URL of the Dify Service API. Replace it with your deployment's API endpoint. variables: api_base_url: default: api.example.com/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - name: Chat Messages description: Operations related to chat messages and interactions. - name: Files description: File upload and preview operations. - name: End Users description: Operations related to end user information. - name: Feedback description: User feedback operations. - name: Conversations description: Operations related to managing conversations. - name: Audio description: Text-to-Speech and Speech-to-Text operations. - name: Applications description: Operations to retrieve application settings and information. - name: Annotations description: Operations related to managing annotations for direct replies. - name: Human Input description: Endpoints for resuming paused workflows that require human input. - name: Workflow Runs description: Operations for executing and managing workflows. - name: Completion Messages description: Operations related to text generation and completion. - name: Knowledge Bases description: >- Operations for managing knowledge bases, including creation, configuration, and retrieval. - name: Documents description: >- Operations for creating, updating, and managing documents within a knowledge base. - name: Chunks description: Operations for managing document chunks and child chunks. - name: Metadata description: >- Operations for managing knowledge base metadata fields and document metadata values. - name: Tags description: Operations for managing knowledge base tags and tag bindings. - name: Models description: Operations for retrieving available models. - name: Knowledge Pipeline description: >- Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution. paths: /completion-messages: post: tags: - Completion Messages summary: Send Completion Message description: |- **Available for**: Text Generator apps. Sends a request to a text-generation app and returns the generated text. operationId: createCompletionMessage requestBody: description: Request body to create a completion message. required: true content: application/json: schema: $ref: '#/components/schemas/CompletionRequest' examples: streaming_example: summary: Request Example - Streaming mode value: inputs: city: San Francisco query: Translate 'hello' to Spanish. response_mode: streaming user: abc-123 files: - type: image transfer_method: remote_url url: https://example.com/logo.png blocking_example: summary: Request Example - Blocking mode value: inputs: city: New York query: 'Summarize the following text: ...' response_mode: blocking user: def-456 responses: '200': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/CompletionResponse' examples: blockingResponse: summary: Response Example - Blocking mode value: 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 text/event-stream: schema: type: string description: >- A stream of Server-Sent Events. Parse it per the [SSE Streaming guide](/en/3.11.x/develop/api/guides/streaming): read `data:` lines, dispatch on the `event` field, skip `ping` (keep-alive every 10 seconds). See `ChunkCompletionEvent` for the event structures. **Stream lifecycle**: the reply streams as `message` chunks and ends with `message_end`. An `error` event ends the stream early; HTTP status stays `200`, so inspect the event payload for details. examples: streamingResponse: summary: Response Example - Streaming mode value: >+ data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595} data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": "'m", "created_at": 1679586595} data: {"event": "message_end", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "id": "5e52ce04-874b-4d27-9045-b3bc80def685", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "metadata": {"usage": {"prompt_tokens": 1033, "prompt_unit_price": "0.001", "prompt_price_unit": "0.001", "prompt_price": "0.0010330", "completion_tokens": 135, "completion_unit_price": "0.002", "completion_price_unit": "0.001", "completion_price": "0.0002700", "total_tokens": 1168, "total_price": "0.0013030", "currency": "USD", "latency": 1.381760165997548}}} '400': description: >- - `app_unavailable` : App unavailable or misconfigured. - `provider_not_initialize` : No valid model provider credentials found. - `completion_request_error` : Text generation failed. - `invalid_param` : The required `user` field is missing. content: application/json: examples: app_unavailable: summary: app_unavailable value: status: 400 code: app_unavailable message: App unavailable, please check your app configurations. provider_not_initialize: summary: provider_not_initialize value: status: 400 code: provider_not_initialize message: >- No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials. completion_request_error: summary: completion_request_error value: status: 400 code: completion_request_error message: Completion request failed. invalid_param: summary: invalid_param value: status: 400 code: invalid_param message: Arg user must be provided. '429': description: '`too_many_requests` : Too many concurrent requests for this app.' content: application/json: examples: too_many_requests: summary: too_many_requests value: status: 429 code: too_many_requests message: >- Too many requests. Please try again later. The current maximum concurrent requests allowed for 5b3d4f2a-1c9e-4a7b-8f6d-2e0c9a1b3d4f is 10. '500': description: '`internal_server_error` : Internal server error.' content: application/json: examples: internal_server_error: summary: internal_server_error value: status: 500 code: internal_server_error message: >- 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. x-codeSamples: - lang: bash label: cURL source: |- curl --request POST \ --url 'https://{api_base_url}/completion-messages' \ --header 'Authorization: Bearer {api_key}' \ --header 'Content-Type: application/json' \ --no-buffer \ --data '{"inputs": {"city": "San Francisco"}, "response_mode": "streaming", "user": "{user}"}' components: schemas: CompletionRequest: type: object required: - inputs - user properties: inputs: type: object description: >- 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/3.11.x/develop/api/applications/get-app-parameters). additionalProperties: true query: type: string default: '' description: >- The text to process. Legacy field; newer apps pass this inside `inputs` instead. response_mode: type: string enum: - streaming - blocking description: >- 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. user: type: string description: >- 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/3.11.x/develop/api/guides/end-user-identity). files: type: array items: $ref: '#/components/schemas/InputFileObject' description: >- Files to attach to the request. For a local file, first upload it via [Upload File](/en/3.11.x/develop/api/files/upload-file), then reference the returned `id` as `upload_file_id` with `transfer_method: local_file`. CompletionResponse: type: object properties: event: type: string description: Event type, fixed as `message`. task_id: type: string format: uuid description: >- Task ID for request tracking and the [Stop Completion Message Generation](/en/3.11.x/develop/api/completion-messages/stop-completion-message-generation) API. id: type: string format: uuid description: Unique ID of this response event. message_id: type: string format: uuid description: >- Unique message ID. Use this as the `message_id` parameter when calling feedback or suggested questions endpoints. mode: type: string description: App mode, fixed as `completion`. answer: type: string description: Complete response content. metadata: type: object description: Metadata including usage and retriever resources. properties: usage: $ref: '#/components/schemas/Usage' retriever_resources: type: array description: List of retriever resources used. items: $ref: '#/components/schemas/RetrieverResource' created_at: type: integer format: int64 description: Message creation timestamp (Unix epoch seconds). InputFileObject: type: object required: - type - transfer_method properties: type: type: string enum: - image - document - audio - video - custom description: File type. transfer_method: type: string enum: - remote_url - local_file description: >- Transfer method: `remote_url` for file URL, `local_file` for uploaded file. url: type: string format: url description: File URL (when `transfer_method` is `remote_url`). upload_file_id: type: string description: >- Uploaded file ID, obtained by uploading through the [Upload File](/en/3.11.x/develop/api/files/upload-file) API in advance (when `transfer_method` is `local_file`). anyOf: - properties: transfer_method: enum: - remote_url url: type: string format: url required: - url not: required: - upload_file_id - properties: transfer_method: enum: - local_file upload_file_id: type: string required: - upload_file_id not: required: - url Usage: type: object description: Model usage information. properties: prompt_tokens: type: integer description: Number of tokens in the prompt. prompt_unit_price: type: string format: decimal description: Unit price per prompt token. prompt_price_unit: type: string format: decimal description: Price unit for prompt tokens. prompt_price: type: string format: decimal description: Total price for prompt tokens. completion_tokens: type: integer description: Number of tokens in the completion. completion_unit_price: type: string format: decimal description: Unit price per completion token. completion_price_unit: type: string format: decimal description: Price unit for completion tokens. completion_price: type: string format: decimal description: Total price for completion tokens. total_tokens: type: integer description: Total number of tokens used. total_price: type: string format: decimal description: Total price for all tokens. currency: type: string description: Currency for pricing. latency: type: number format: double description: Latency in seconds. RetrieverResource: type: object description: Citation and attribution information for a retriever resource. properties: id: type: string format: uuid description: Unique ID of the retriever resource. message_id: type: string format: uuid description: ID of the message this resource belongs to. position: type: integer description: Position of the resource in the list. dataset_id: type: string format: uuid description: ID of the knowledge base. dataset_name: type: string description: Name of the knowledge base. document_id: type: string format: uuid description: ID of the document. document_name: type: string description: Name of the document. data_source_type: type: string description: Type of the data source. segment_id: type: string format: uuid description: ID of the specific chunk within the document. score: type: number format: float description: Similarity score of the resource. hit_count: type: integer description: Number of times this chunk was hit. word_count: type: integer description: Word count of the chunk. segment_position: type: integer description: Position of the chunk within the document. index_node_hash: type: string description: Hash of the index node. content: type: string description: Content snippet from the resource. summary: type: string nullable: true description: Summary of the chunk content. created_at: type: integer format: int64 description: Creation timestamp (Unix epoch seconds). securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API_KEY description: >- 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](/en/3.11.x/develop/api/guides/get-started)). Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`). ````