​

Overview

The text generation application offers non-session support and is ideal for translation, article writing, summarization AI, and more.

​

Base URL

https://api.dify.ai/v1

​

Authentication

The Service API uses API-Key authentication.

Important: Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.

For all API requests, include your API Key in the Authorization HTTP Header:

Authorization: Bearer {API_KEY}

​

API Endpoints

​

Send Message

POST /completion-messages

Send a request to the text generation application.

​

Request Body

• inputs (object) Required

  • Allows the entry of various variable values defined by the App
  • Contains multiple key/value pairs, each key corresponding to a specific variable
  • At least one key/value pair required

• response_mode (string) Required

  • Modes supported:
    • streaming: Streaming mode (recommended), implements typewriter-like output through SSE
    • blocking: Blocking mode, returns result after execution completes
      • Note: Due to Cloudflare restrictions, requests will timeout after 100 seconds

• user (string) Required

  • User identifier for retrieval and statistics
  • Should be uniquely defined within the application

• files (array[object]) Optional

  • File list for image input with text understanding
  • Available only when model supports Vision capability
  • Properties:
    • type (string): Supported type: image
    • transfer_method (string): ‘remote_url’ or ‘local_file’
    • url (string): Image URL (for remote_url)
    • upload_file_id (string): Uploaded file ID (for local_file)

​

Response

Blocking Mode Response Returns a CompletionResponse object with Content-Type: application/json

interface CompletionResponse {
  message_id: string;
  mode: string;
  answer: string;
  metadata: {
    usage: Usage;
  };
  created_at: number;
}

Streaming Mode Response Returns ChunkCompletionResponse stream with Content-Type: text/event-stream

Events:

• message: LLM text chunk event
• message_end: Stream end event
• message_replace: Content replacement event
• error: Exception event
• ping: Keep-alive event (every 10s)

​

Example Requests

curl -X POST 'https://api.dify.ai/v1/completion-messages' \
-H 'Authorization: Bearer {api_key}' \
-H 'Content-Type: application/json' \
--data-raw '{
    "inputs": {
        "query": "hello world."
    },
    "response_mode": "streaming",
    "user": "abc-123",
    "files": [
      {
        "type": "image",
        "transfer_method": "remote_url",
        "url": "https://cloud.dify.ai/logo/logo-site.png"
      }
    ]
}'

​

File Upload

POST /files/upload

Upload files (currently only images) for multimodal understanding.

​

Supported Formats

• png
• jpg
• jpeg
• webp
• gif

​

Request Body

Requires multipart/form-data:

• file (File) Required
• user (string) Required

​

Response

interface FileUploadResponse {
  id: string;
  name: string;
  size: number;
  extension: string;
  mime_type: string;
  created_by: string;
  created_at: number;
}

​

Stop Generate

POST /completion-messages/:task_id/stop

Stop ongoing generation (streaming mode only).

​

Request Body

• user (string) Required

​

Response

{
    "result": "success"
}

​

Message Feedback

POST /messages/:message_id/feedbacks

Submit user feedback on messages.

​

Request Body

• rating (string) Required: “like” | “dislike” | null
• user (string) Required

​

Response

{
    "result": "success"
}

​

Get Application Information

GET /parameters

Retrieve application configuration and parameters.

​

Query Parameters

• user (string) Required

​

Response

interface ApplicationInfo {
  more_like_this: {
    enabled: boolean;
  };
  user_input_form: Array<{
    'text-input' | 'paragraph' | 'select': {
      label: string;
      variable: string;
      required: boolean;
      default: string;
      options?: string[];
    };
  }>;
  file_upload: {
    image: {
      enabled: boolean;
      number_limits: number;
      transfer_methods: string[];
    };
  };
  system_parameters: {
    image_file_size_limit: string;
  };
}

​

Types

​

Usage

interface Usage {
  prompt_tokens: number;
  prompt_unit_price: string;
  prompt_price_unit: string;
  prompt_price: string;
  completion_tokens: number;
  completion_unit_price: string;
  completion_price_unit: string;
  completion_price: string;
  total_tokens: number;
  total_price: string;
  currency: string;
  latency: number;
}

​

Error Codes

Common error codes you may encounter:

• 400: invalid_param - Abnormal parameter input
• 400: app_unavailable - App configuration unavailable
• 400: provider_not_initialize - No available model credential configuration
• 400: provider_quota_exceeded - Model invocation quota insufficient
• 400: model_currently_not_support - Current model unavailable
• 400: completion_request_error - Text generation failed
• 500: Internal server error