centersl/dify-docs
1
0
Fork 0
mirror of https://github.com/langgenius/dify-docs.git synced 2026-03-27 13:28:32 +07:00
Code Issues Packages Projects Releases Wiki Activity
Files
2da02258f4757e59ffb69cecd136095396f8deea
dify-docs/en/api-reference/openapi_completion.json
Chenhe Gu 08e9e11c90 Replace main with revamp (#547)
2025-11-26 04:46:31 -08:00

1218 lines
48 KiB
JSON
Raw Blame History

{
"openapi": "3.0.1",
"info": {
"title": "Completion App API",
"description": "The text generation application offers non-session support and is ideal for translation, article writing, summarization AI, and more.",
"version": "1.0.0"
},
"servers": [
{
"url": "{api_base_url}",
"description": "The base URL for the Completion App API. Replace {api_base_url} with the actual API base URL provided for your application (e.g., from props.appDetail.api_base_url).",
"variables": {
"api_base_url": {
"default": "https://api.dify.ai/v1",
"description": "Actual base URL of the API"
}
}
}
],
"security": [
{
"ApiKeyAuth": []
}
],
"paths": {
"/completion-messages": {
"post": {
"summary": "Create Completion Message",
"description": "Send a request to the text generation application.",
"operationId": "createCompletionMessage",
"tags": ["Completion"],
"requestBody": {
"description": "Request body to create a completion message.",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompletionRequest"
},
"examples": {
"streaming_example": {
"summary": "Streaming mode example",
"value": {
"inputs": {"query": "Hello, world!"},
"response_mode": "streaming",
"user": "abc-123"
}
},
"blocking_example": {
"summary": "Blocking mode example",
"value": {
"inputs": {"query": "Translate this to French: Hello"},
"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.\n- If `response_mode` is `blocking`, returns `application/json` with a `CompletionResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a `ChunkCompletionResponse` stream.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompletionResponse"
},
"examples": {
"blockingResponse": {
"summary": "Example of a blocking mode response",
"value": {
"event": "message",
"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. Each event is a JSON object prefixed with 'data: ' and suffixed with '\\n\\n'. See `ChunkCompletionEvent` for possible event structures."
},
"examples": {
"streamingResponse": {
"summary": "Example of a streaming mode response",
"value": "data: {\"event\": \"message\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \" I\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \"'m\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message_end\", \"id\": \"5e52ce04-874b-4d27-9045-b3bc80def685\", \"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}}}\n\ndata: {\"event\": \"tts_message\", \"task_id\": \"3bf8a0bb-e73b-4690-9e66-4e429bad8ee7\", \"message_id\": \"a8bdc41c-13b2-4c18-bfd9-054b9803038c\", \"created_at\": 1721205487, \"audio\": \"base64encodedaudio...\"}\n\ndata: {\"event\": \"tts_message_end\", \"task_id\": \"3bf8a0bb-e73b-4690-9e66-4e429bad8ee7\", \"message_id\": \"a8bdc41c-13b2-4c18-bfd9-054b9803038c\", \"created_at\": 1721205487, \"audio\": \"\"}\n\n"
}
}
}
}
},
"400": {
"description": "Bad Request. Possible error codes:\n- `invalid_param`: Abnormal parameter input.\n- `app_unavailable`: App configuration unavailable.\n- `provider_not_initialize`: No available model credential configuration.\n- `provider_quota_exceeded`: Model invocation quota insufficient.\n- `model_currently_not_support`: Current model unavailable.\n- `completion_request_error`: Text generation failed.",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
},
"404": {
"description": "Conversation does not exist.",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
}
}
}
},
"/files/upload": {
"post": {
"summary": "File Upload",
"description": "Upload a file (currently only images are supported) for use when sending messages, enabling multimodal understanding of images and text. Supports png, jpg, jpeg, webp, gif formats. Uploaded files are for use by the current end-user only.",
"operationId": "uploadFile",
"tags": ["Files"],
"requestBody": {
"description": "File upload request. Requires multipart/form-data.",
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": ["file", "user"],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "The file to be uploaded. Supported image types: png, jpg, jpeg, webp, gif."
},
"user": {
"type": "string",
"description": "User identifier, defined by the developer's rules, must be unique within the application."
}
}
}
}
}
},
"responses": {
"200": {
"description": "File uploaded successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileUploadResponse"
},
"examples": {
"success": {
"value": {
"id": "72fa9618-8f89-4a37-9b33-7e1178a24a67",
"name": "example.png",
"size": 1024,
"extension": "png",
"mime_type": "image/png",
"created_by": "6ad1ab0a-73ff-4ac1-b9e4-cdb312f71f13",
"created_at": 1577836800
}
}
}
}
}
},
"400": {
"description": "Bad Request. Possible error codes:\n- `no_file_uploaded`: A file must be provided.\n- `too_many_files`: Currently only one file is accepted.\n- `unsupported_preview`: The file does not support preview.\n- `unsupported_estimate`: The file does not support estimation.",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
},
"413": {
"description": "`file_too_large`: The file is too large.",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
},
"415": {
"description": "`unsupported_file_type`: Unsupported extension. Currently only document files are accepted (Note: description says image types png, jpg, etc. are supported for this endpoint, but this error message refers to document files. Clarification might be needed from source documentation).",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
},
"503": {
"description": "Service Unavailable. Possible error codes:\n- `s3_connection_failed`: Unable to connect to S3 service.\n- `s3_permission_denied`: No permission to upload files to S3.\n- `s3_file_too_large`: File exceeds S3 size limit.",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
}
}
}
},
"/completion-messages/{task_id}/stop": {
"post": {
"summary": "Stop Generate",
"description": "Stops a generation task. Only supported in streaming mode.",
"operationId": "stopGenerate",
"tags": ["Completion"],
"parameters": [
{
"name": "task_id",
"in": "path",
"required": true,
"description": "Task ID, can be obtained from the streaming chunk return of a `/completion-messages` request.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["user"],
"properties": {
"user": {
"type": "string",
"description": "User identifier, used to define the identity of the end-user, must be consistent with the user passed in the send message interface."
}
}
},
"examples": {
"example":{
"value": {
"user": "abc-123"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Stop request successful.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"result": {
"type": "string",
"example": "success"
}
}
},
"examples": {
"success": {
"value": {
"result": "success"
}
}
}
}
}
}
}
}
},
"/messages/{message_id}/feedbacks": {
"post": {
"summary": "Message Feedback",
"description": "End-users can provide feedback messages, facilitating application developers to optimize expected outputs.",
"operationId": "postMessageFeedback",
"tags": ["Feedback"],
"parameters": [
{
"name": "message_id",
"in": "path",
"required": true,
"description": "Message ID for which feedback is being provided.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageFeedbackRequest"
},
"examples": {
"like_example": {
"value": {
"rating": "like",
"user": "abc-123",
"content": "message feedback information"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Feedback submitted successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"result": {
"type": "string",
"example": "success"
}
}
},
"examples": {
"success": {
"value": {
"result": "success"
}
}
}
}
}
}
}
}
},
"/app/feedbacks": {
"get": {
"summary": "Get feedbacks of application",
"description": "Get application's feedbacks.",
"operationId": "getAppFeedbacks",
"tags": ["Feedback"],
"parameters": [
{
"name": "page",
"in": "query",
"description": "(optional) Pagination page number. Default: 1",
"required": false,
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "limit",
"in": "query",
"description": "(optional) Records per page. Default: 20",
"required": false,
"schema": {
"type": "integer",
"default": 20
}
}
],
"responses": {
"200": {
"description": "A list of application feedbacks.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppFeedbacksResponse"
},
"examples": {
"success": {
"value": {
"data": [
{
"id": "8c0fbed8-e2f9-49ff-9f0e-15a35bdd0e25",
"app_id": "f252d396-fe48-450e-94ec-e184218e7346",
"conversation_id": "2397604b-9deb-430e-b285-4726e51fd62d",
"message_id": "709c0b0f-0a96-4a4e-91a4-ec0889937b11",
"rating": "like",
"content": "message feedback information-3",
"from_source": "user",
"from_end_user_id": "74286412-9a1a-42c1-929c-01edb1d381d5",
"from_account_id": null,
"created_at": "2025-04-24T09:24:38",
"updated_at": "2025-04-24T09:24:38"
}
]
}
}
}
}
}
}
}
}
},
"/text-to-audio": {
"post": {
"summary": "Text to Audio",
"description": "Convert text to speech.",
"operationId": "textToAudio",
"tags": ["TTS"],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TextToAudioRequest"
},
"examples": {
"example": {
"value": {
"message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290",
"text": "Hello Dify",
"user": "abc-123"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Audio file generated successfully.",
"content": {
"audio/wav": {
"schema": {
"type": "string",
"format": "binary",
"description": "The generated audio file in WAV format."
}
}
},
"headers": {
"Content-Type": {
"description": "The content type of the response, typically `audio/wav` or `audio/mp3` depending on server configuration.",
"schema": {
"type": "string",
"example": "audio/wav"
}
}
}
}
}
}
},
"/info": {
"get": {
"summary": "Get Application Basic Information",
"description": "Used to get basic information about this application.",
"operationId": "getAppInfo",
"tags": ["Application"],
"responses": {
"200": {
"description": "Basic information of the application.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppInfoResponse"
},
"examples": {
"success": {
"value": {
"name": "My App",
"description": "This is my app.",
"tags": [
"tag1",
"tag2"
]
}
}
}
}
}
}
}
}
},
"/parameters": {
"get": {
"summary": "Get Application Parameters Information",
"description": "Used at the start of entering the page to obtain information such as features, input parameter names, types, and default values.",
"operationId": "getAppParameters",
"tags": ["Application"],
"responses": {
"200": {
"description": "Application parameters information.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppParametersResponse"
},
"examples": {
"success": {
"value": {
"opening_statement": "Hello!",
"suggested_questions_after_answer": {
"enabled": true
},
"speech_to_text": {
"enabled": true
},
"retriever_resource": {
"enabled": true
},
"annotation_reply": {
"enabled": true
},
"user_input_form": [
{
"paragraph": {
"label": "Query",
"variable": "query",
"required": true,
"default": ""
}
}
],
"file_upload": {
"image": {
"enabled": false,
"number_limits": 3,
"detail": "high",
"transfer_methods": [
"remote_url",
"local_file"
]
}
},
"system_parameters": {
"file_size_limit": 15,
"image_file_size_limit": 10,
"audio_file_size_limit": 50,
"video_file_size_limit": 100
}
}
}
}
}
}
}
}
}
},
"/site": {
"get": {
"summary": "Get Application WebApp Settings",
"description": "Used to get the WebApp settings of the application.",
"operationId": "getWebAppSettings",
"tags": ["Application"],
"responses": {
"200": {
"description": "WebApp settings of the application.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAppSettingsResponse"
},
"examples": {
"success": {
"value": {
"title": "My App",
"chat_color_theme": "#ff4a4a",
"chat_color_theme_inverted": false,
"icon_type": "emoji",
"icon": "😄",
"icon_background": "#FFEAD5",
"icon_url": null,
"description": "This is my app.",
"copyright": "all rights reserved",
"privacy_policy": "",
"custom_disclaimer": "All generated by AI",
"default_language": "en-US",
"show_workflow_steps": false,
"use_icon_as_answer_icon": false
}
}
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "API_KEY",
"description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with 'Bearer '. Example: `Authorization: Bearer {API_KEY}`. **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.**"
}
},
"schemas": {
"CompletionRequest": {
"type": "object",
"properties": {
"inputs": {
"type": "object",
"description": "Allows the entry of various variable values defined by the App. The `inputs` parameter contains multiple key/value pairs, with each key corresponding to a specific variable and each value being the specific value for that variable. The text generation application requires at least one key/value pair to be inputted.",
"required": ["query"],
"properties": {
"query": {
"type": "string",
"description": "The input text, the content to be processed."
}
},
"additionalProperties": {
"type": "string"
},
"example": {"query": "Translate 'hello' to Spanish."}
},
"response_mode": {
"type": "string",
"enum": ["streaming", "blocking"],
"description": "The mode of response return.\n- `streaming`: Streaming mode (recommended), implements a typewriter-like output through SSE ([Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)).\n- `blocking`: Blocking mode, returns result after execution is complete. (Requests may be interrupted if the process is long). *Due to Cloudflare restrictions, the request will be interrupted without a return after 100 seconds in blocking mode for long processes.*",
"example": "streaming"
},
"user": {
"type": "string",
"description": "User identifier, used to define the identity of the end-user for retrieval and statistics. Should be uniquely defined by the developer within the application.",
"example": "user-12345"
},
"files": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InputFileObject"
},
"description": "File list, suitable for inputting files (images) combined with text understanding and answering questions, available only when the model supports Vision capability."
}
},
"required": [
"inputs"
]
},
"InputFileObject": {
"type": "object",
"required": ["type", "transfer_method"],
"properties": {
"type": {
"type": "string",
"enum": ["image"],
"description": "Supported type: `image` (currently only supports image type)."
},
"transfer_method": {
"type": "string",
"enum": ["remote_url", "local_file"],
"description": "Transfer method, `remote_url` for image URL / `local_file` for file upload"
},
"url": {
"type": "string",
"format": "url",
"description": "Image URL (when the transfer method is `remote_url`)"
},
"upload_file_id": {
"type": "string",
"description": "Uploaded file ID, which must be obtained by uploading through the File Upload API in advance (when the 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"] }
}
],
"example": {
"type": "image",
"transfer_method": "remote_url",
"url": "https://example.com/image.png"
}
},
"CompletionResponse": {
"type": "object",
"description": "Response object for blocking mode completion.",
"properties": {
"event": {
"type": "string",
"description": "Event type, for blocking mode this is typically 'message'.",
"example": "message"
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "Unique message ID."
},
"mode": {
"type": "string",
"description": "App mode, fixed as `completion` for this response type (Note: MD also mentions 'chat', using 'completion' from example).",
"example": "completion"
},
"answer": {
"type": "string",
"description": "Complete response content."
},
"metadata": {
"type": "object",
"properties": {
"usage": {
"$ref": "#/components/schemas/Usage"
},
"retriever_resources": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RetrieverResource"
},
"description": "Citation and Attribution List."
}
}
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Message creation timestamp (Unix epoch).",
"example": 1705395332
}
}
},
"ChunkCompletionEvent": {
"type": "object",
"description": "Structure of a Server-Sent Event chunk in streaming mode. The `event` field determines the structure of the rest of the object.",
"discriminator": {
"propertyName": "event",
"mapping": {
"message": "#/components/schemas/StreamEventMessage",
"message_end": "#/components/schemas/StreamEventMessageEnd",
"tts_message": "#/components/schemas/StreamEventTtsMessage",
"tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd",
"message_replace": "#/components/schemas/StreamEventMessageReplace",
"error": "#/components/schemas/StreamEventError",
"ping": "#/components/schemas/StreamEventPing"
}
},
"properties": {
"event": {
"type": "string",
"enum": ["message", "message_end", "tts_message", "tts_message_end", "message_replace", "error", "ping"],
"description": "The type of event."
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "Task ID, used for request tracking and the Stop Generate API. Not present in 'ping' event."
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "Unique message ID. Not present in 'ping' event."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Creation timestamp (Unix epoch). Not present in 'ping' event.",
"example": 1705395332
}
},
"required": ["event"]
},
"StreamEventMessage": {
"allOf": [
{ "$ref": "#/components/schemas/ChunkCompletionEvent" },
{
"type": "object",
"description": "LLM returns text chunk event.",
"properties": {
"answer": {
"type": "string",
"description": "LLM returned text chunk content."
}
},
"required": ["task_id", "message_id", "answer", "created_at"]
}
]
},
"StreamEventMessageEnd": {
"allOf": [
{ "$ref": "#/components/schemas/ChunkCompletionEvent" },
{
"type": "object",
"description": "Message end event, receiving this event means streaming has ended.",
"properties": {
"metadata": {
"type": "object",
"properties": {
"usage": { "$ref": "#/components/schemas/Usage" },
"retriever_resources": {
"type": "array",
"items": { "$ref": "#/components/schemas/RetrieverResource" },
"description": "Citation and Attribution List."
}
}
}
},
"required": ["task_id", "message_id", "metadata"]
}
]
},
"StreamEventTtsMessage": {
"allOf": [
{ "$ref": "#/components/schemas/ChunkCompletionEvent" },
{
"type": "object",
"description": "TTS audio stream event. The content is an audio block in Mp3 format, encoded as a base64 string. (This message is available only when auto-play is enabled)",
"properties": {
"audio": {
"type": "string",
"format": "byte",
"description": "The audio after speech synthesis, encoded in base64 text content. When playing, simply decode the base64 and feed it into the player."
}
},
"required": ["task_id", "message_id", "audio", "created_at"]
}
]
},
"StreamEventTtsMessageEnd": {
"allOf": [
{ "$ref": "#/components/schemas/ChunkCompletionEvent" },
{
"type": "object",
"description": "TTS audio stream end event.",
"properties": {
"audio": {
"type": "string",
"description": "The end event has no audio, so this is an empty string."
}
},
"required": ["task_id", "message_id", "audio", "created_at"]
}
]
},
"StreamEventMessageReplace": {
"allOf": [
{ "$ref": "#/components/schemas/ChunkCompletionEvent" },
{
"type": "object",
"description": "Message content replacement event. When output content moderation is enabled, if the content is flagged, then the message content will be replaced with a preset reply through this event.",
"properties": {
"answer": {
"type": "string",
"description": "Replacement content (directly replaces all LLM reply text)."
}
},
"required": ["task_id", "message_id", "answer", "created_at"]
}
]
},
"StreamEventError": {
"allOf": [
{ "$ref": "#/components/schemas/ChunkCompletionEvent" },
{
"type": "object",
"description": "Exceptions that occur during the streaming process will be output in the form of stream events, and reception of an error event will end the stream.",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code."
},
"code": {
"type": "string",
"description": "Error code."
},
"message": {
"type": "string",
"description": "Error message."
}
},
"required": ["task_id", "message_id", "status", "code", "message"]
}
]
},
"StreamEventPing": {
"allOf": [
{ "$ref": "#/components/schemas/ChunkCompletionEvent" },
{
"type": "object",
"description": "Ping event every 10 seconds to keep the connection alive. This event type does not contain other fields like task_id or message_id."
}
]
},
"Usage": {
"type": "object",
"description": "Model usage information.",
"properties": {
"prompt_tokens": { "type": "integer" },
"prompt_unit_price": { "type": "string", "format": "decimal" },
"prompt_price_unit": { "type": "string", "format": "decimal" },
"prompt_price": { "type": "string", "format": "decimal" },
"completion_tokens": { "type": "integer" },
"completion_unit_price": { "type": "string", "format": "decimal" },
"completion_price_unit": { "type": "string", "format": "decimal" },
"completion_price": { "type": "string", "format": "decimal" },
"total_tokens": { "type": "integer" },
"total_price": { "type": "string", "format": "decimal" },
"currency": { "type": "string", "example": "USD" },
"latency": { "type": "number", "format": "double" }
}
},
"RetrieverResource": {
"type": "object",
"description": "Citation and Attribution information for a resource.",
"properties": {
"document_id": { "type": "string", "description": "ID of the retrieved document." },
"segment_id": { "type": "string", "description": "ID of the specific segment within the document." },
"score": { "type": "number", "format": "float", "description": "Relevance score of the resource." },
"content": { "type": "string", "description": "Content snippet from the resource." }
}
},
"FileUploadResponse": {
"type": "object",
"properties": {
"id": { "type": "string", "format": "uuid", "description": "ID of the uploaded file." },
"name": { "type": "string", "description": "File name." },
"size": { "type": "integer", "description": "File size (bytes)." },
"extension": { "type": "string", "description": "File extension." },
"mime_type": { "type": "string", "description": "File mime-type." },
"created_by": { "type": "string", "format": "uuid", "description": "End-user ID who uploaded the file." },
"created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp (Unix epoch).", "example": 1577836800 }
}
},
"MessageFeedbackRequest": {
"type": "object",
"properties": {
"rating": {
"type": "string",
"enum": ["like", "dislike", null],
"nullable": true,
"description": "Upvote as `like`, downvote as `dislike`, revoke upvote/downvote as `null`."
},
"user": {
"type": "string",
"description": "User identifier, defined by the developer's rules, must be unique within the application."
},
"content": {
"type": "string",
"description": "The specific content of message feedback."
}
},
"required": ["user"]
},
"AppFeedbacksResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FeedbackItem"
},
"description": "List of application feedback items."
}
}
},
"FeedbackItem": {
"type": "object",
"properties": {
"id": { "type": "string", "format": "uuid" },
"app_id": { "type": "string", "format": "uuid" },
"conversation_id": { "type": "string", "format": "uuid" },
"message_id": { "type": "string", "format": "uuid" },
"rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true },
"content": { "type": "string" },
"from_source": { "type": "string" },
"from_end_user_id": { "type": "string", "format": "uuid" },
"from_account_id": { "type": "string", "format": "uuid", "nullable": true },
"created_at": { "type": "string", "format": "date-time" },
"updated_at": { "type": "string", "format": "date-time" }
}
},
"TextToAudioRequest": {
"type": "object",
"properties": {
"message_id": {
"type": "string",
"format": "uuid",
"description": "For text messages generated by Dify, simply pass the generated message-id directly. The backend will use the message-id to look up the corresponding content and synthesize the voice information directly. If both message_id and text are provided simultaneously, the message_id is given priority."
},
"text": {
"type": "string",
"description": "Speech generated content. Used if message_id is not provided or not found."
},
"user": {
"type": "string",
"description": "The user identifier, defined by the developer, must ensure uniqueness within the app."
}
},
"required": ["user"],
"description": "At least one of `message_id` or `text` must be provided, along with `user`."
},
"AppInfoResponse": {
"type": "object",
"properties": {
"name": { "type": "string", "description": "Application name." },
"description": { "type": "string", "description": "Application description." },
"tags": {
"type": "array",
"items": { "type": "string" },
"description": "Application tags."
}
}
},
"AppParametersResponse": {
"type": "object",
"properties": {
"opening_statement": { "type": "string", "description": "Opening statement." },
"suggested_questions": {
"type": "array",
"items": { "type": "string" },
"description": "List of suggested questions for the opening."
},
"suggested_questions_after_answer": {
"type": "object",
"properties": {
"enabled": { "type": "boolean", "description": "Whether suggesting questions after an answer is enabled." }
}
},
"speech_to_text": {
"type": "object",
"properties": {
"enabled": { "type": "boolean", "description": "Whether speech to text is enabled." }
}
},
"retriever_resource": {
"type": "object",
"properties": {
"enabled": { "type": "boolean", "description": "Whether citation and attribution (retriever resource) is enabled." }
}
},
"annotation_reply": {
"type": "object",
"properties": {
"enabled": { "type": "boolean", "description": "Whether annotation reply is enabled." }
}
},
"user_input_form": {
"type": "array",
"items": { "$ref": "#/components/schemas/UserInputFormItem" },
"description": "User input form configuration."
},
"file_upload": {
"type": "object",
"description": "File upload configuration.",
"properties": {
"image": {
"type": "object",
"description": "Image settings. Currently only supports image types: png, jpg, jpeg, webp, gif.",
"properties": {
"enabled": { "type": "boolean", "description": "Whether image upload is enabled." },
"number_limits": { "type": "integer", "description": "Image number limit, default is 3." },
"detail": {"type": "string", "description": "Detail level for image processing (e.g., 'high'). From example, not in main description."},
"transfer_methods": {
"type": "array",
"items": { "type": "string", "enum": ["remote_url", "local_file"] },
"description": "List of transfer methods, must choose at least one if enabled."
}
}
}
}
},
"system_parameters": {
"type": "object",
"description": "System parameters.",
"properties": {
"file_size_limit": { "type": "integer", "description": "Document upload size limit (MB)." },
"image_file_size_limit": { "type": "integer", "description": "Image file upload size limit (MB)." },
"audio_file_size_limit": { "type": "integer", "description": "Audio file upload size limit (MB)." },
"video_file_size_limit": { "type": "integer", "description": "Video file upload size limit (MB)." }
}
}
}
},
"UserInputFormItem": {
"type": "object",
"description": "Represents a single item in the user input form. It will have one of the specific control type keys.",
"oneOf": [
{ "$ref": "#/components/schemas/TextInputControlWrapper" },
{ "$ref": "#/components/schemas/ParagraphControlWrapper" },
{ "$ref": "#/components/schemas/SelectControlWrapper" }
]
},
"TextInputControlWrapper": {
"type": "object",
"properties": {
"text-input": { "$ref": "#/components/schemas/TextInputControl" }
},
"required": ["text-input"]
},
"ParagraphControlWrapper": {
"type": "object",
"properties": {
"paragraph": { "$ref": "#/components/schemas/ParagraphControl" }
},
"required": ["paragraph"]
},
"SelectControlWrapper": {
"type": "object",
"properties": {
"select": { "$ref": "#/components/schemas/SelectControl" }
},
"required": ["select"]
},
"TextInputControl": {
"type": "object",
"description": "Text input control.",
"properties": {
"label": { "type": "string", "description": "Variable display label name." },
"variable": { "type": "string", "description": "Variable ID." },
"required": { "type": "boolean", "description": "Whether it is required." },
"default": { "type": "string", "description": "Default value." }
},
"required": ["label", "variable", "required"]
},
"ParagraphControl": {
"type": "object",
"description": "Paragraph text input control.",
"properties": {
"label": { "type": "string", "description": "Variable display label name." },
"variable": { "type": "string", "description": "Variable ID." },
"required": { "type": "boolean", "description": "Whether it is required." },
"default": { "type": "string", "description": "Default value." }
},
"required": ["label", "variable", "required"]
},
"SelectControl": {
"type": "object",
"description": "Dropdown control.",
"properties": {
"label": { "type": "string", "description": "Variable display label name." },
"variable": { "type": "string", "description": "Variable ID." },
"required": { "type": "boolean", "description": "Whether it is required." },
"default": { "type": "string", "description": "Default value." },
"options": {
"type": "array",
"items": { "type": "string" },
"description": "Option values."
}
},
"required": ["label", "variable", "required", "options"]
},
"WebAppSettingsResponse": {
"type": "object",
"properties": {
"title": { "type": "string", "description": "WebApp name." },
"chat_color_theme": { "type": "string", "description": "Chat color theme, in hex format (e.g., #RRGGBB)." },
"chat_color_theme_inverted": { "type": "boolean", "description": "Whether the chat color theme is inverted." },
"icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "Icon type." },
"icon": { "type": "string", "description": "Icon. If it's `emoji` type, it's an emoji symbol; if it's `image` type, it's an image URL." },
"icon_background": { "type": "string", "description": "Background color in hex format (e.g., #RRGGBB)." },
"icon_url": { "type": "string", "format": "url", "nullable": true, "description": "Icon URL (likely refers to image type if `icon` field is just a name/id)." },
"description": { "type": "string", "description": "Description." },
"copyright": { "type": "string", "description": "Copyright information." },
"privacy_policy": { "type": "string", "description": "Privacy policy link." },
"custom_disclaimer": { "type": "string", "description": "Custom disclaimer." },
"default_language": { "type": "string", "description": "Default language (e.g., en-US)." },
"show_workflow_steps": { "type": "boolean", "description": "Whether to show workflow details." },
"use_icon_as_answer_icon": { "type": "boolean", "description": "Whether to replace 🤖 in chat with the WebApp icon." }
}
},
"ErrorResponse": {
"type": "object",
"properties": {
"status": { "type": "integer", "description": "HTTP status code." },
"code": { "type": "string", "description": "Error code specific to the application." },
"message": { "type": "string", "description": "A human-readable error message." }
}
}
}
},
"tags": [
{ "name": "Completion", "description": "Operations related to text generation and completion." },
{ "name": "Files", "description": "Operations related to file management." },
{ "name": "Feedback", "description": "Operations related to user feedback." },
{ "name": "TTS", "description": "Operations related to Text-to-Speech." },
{ "name": "Application", "description": "Operations to retrieve application settings and information." }
]
}
Reference in New Issue View Git Blame Copy Permalink