Kie.ai API

https://docs.kie.ai/
Admin
Kie.ai provides affordable and stable AI APIs for seamless integration into projects, offering...
Tokens:935,036
Snippets:3,168
Trust Score:9.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### Complete Example Code

Source: https://docs.kie.ai/common-api/webhook-verification

Example code demonstrating how to verify a webhook signature.

```APIDOC
## Complete Example Code

### Description
Example code for verifying webhook signatures.

### Code
Not specified in source.
```

--------------------------------

### Python Callback Example

Source: https://docs.kie.ai/suno-api/generate-music-callbacks

Example Flask server that receives callbacks and processes the music generation results.

```APIDOC
## Python Callback Example

### Description
Example code for receiving callbacks in Python using Flask.

### Method
POST

### Endpoint
/suno-callback

### Code Example
```python
from flask import Flask, request, jsonify
import json

app = Flask(__name__)

@app.route('/suno-callback', methods=['POST'])
def handle_callback():
    data = request.json
    
    code = data.get('code')
    msg = data.get('msg')
    callback_data = data.get('data', {})
    task_id = callback_data.get('task_id')
    callback_type = callback_data.get('callbackType')
    
    print(f"Received callback: {task_id}, status: {code}, type: {callback_type}, message: {msg}")
    
    if code == 200:
        # Task completed successfully
        if callback_type == 'complete':
            audio_list = callback_data.get('data', [])
            print(f"Music generation completed, generated {len(audio_list)} tracks")
            
            for audio in audio_list:
                print(f"Audio ID: {audio['id']}")
                print(f"Audio URL: {audio['audio_url']}")
                print(f"Title: {audio['title']}")
                print(f"Duration: {audio['duration']} seconds")
                
        elif callback_type == 'first':
            print("First track completed")
            
        elif callback_type == 'text':
            print("Text generation completed")
            
    else:
        # Task failed
        print(f"Task failed: {msg}")
        
        # Handle failure cases...
    
    # Return 200 status code to confirm callback received
    return jsonify({'status': 'received'}), 200

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=3000)
```
```

--------------------------------

### PHP Callback Example

Source: https://docs.kie.ai/suno-api/generate-music-callbacks

Example PHP script that receives callbacks and processes the music generation results.

```APIDOC
## PHP Callback Example

### Description
Example code for receiving callbacks in PHP.

### Method
POST

### Endpoint
/suno-callback

### Code Example
```php
<?php
header('Content-Type: application/json');

// Get the request body
$body = file_get_contents('php://input');
$data = json_decode($body, true);

$code = $data['code'] ?? null;
$msg = $data['msg'] ?? null;
$callbackData = $data['data'] ?? [];
$taskId = $callbackData['task_id'] ?? null;
$callbackType = $callbackData['callbackType'] ?? null;

echo "Received callback: $taskId, status: $code, type: $callbackType, message: $msg\n";

if ($code == 200) {
    // Task completed successfully
    if ($callbackType == 'complete') {
        $audioList = $callbackData['data'] ?? [];
        echo "Music generation completed, generated " . count($audioList) . " tracks\n";
        
        foreach ($audioList as $audio) {
            echo "Audio ID: " . $audio['id'] . "\n";
            echo "Audio URL: " . $audio['audio_url'] . "\n";
            echo "Title: " . $audio['title'] . "\n";
            echo "Duration: " . $audio['duration'] . " seconds\n";
        }
        
    } elseif ($callbackType == 'first') {
        echo "First track completed\n";
        
    } elseif ($callbackType == 'text') {
        echo "Text generation completed\n";
    }
    
} else {
    // Task failed
    echo "Task failed: $msg\n";
    
    // Handle failure cases...
}

// Return 200 status code to confirm callback received
echo json_encode(['status' => 'received']);
?>
```
```

--------------------------------

### Node.js Callback Example

Source: https://docs.kie.ai/suno-api/generate-music-callbacks

Example Express.js server that receives callbacks and processes the music generation results.

```APIDOC
## Node.js Callback Example

### Description
Example code for receiving callbacks in Node.js using Express.

### Method
POST

### Endpoint
/suno-callback

### Code Example
```javascript
const express = require('express');
const app = express();

app.use(express.json());

app.post('/suno-callback', (req, res) => {
  const { code, msg, data } = req.body;
  
  console.log('Received callback:', {
    taskId: data.task_id,
    status: code,
    message: msg,
    callbackType: data.callbackType
  });
  
  if (code === 200) {
    // Task completed successfully
    if (data.callbackType === 'complete') {
      console.log('Music generation completed:', data.data);
      
      // Process generated music data
      data.data.forEach(audio => {
        console.log(`Audio ID: ${audio.id}`);
        console.log(`Audio URL: ${audio.audio_url}`);
        console.log(`Title: ${audio.title}`);
        console.log(`Duration: ${audio.duration} seconds`);
      });
      
    } else if (data.callbackType === 'first') {
      console.log('First track completed');
      
    } else if (data.callbackType === 'text') {
      console.log('Text generation completed');
    }
    
  } else {
    // Task failed
    console.log('Task failed:', msg);
    
    // Handle failure cases...
  }
  
  // Return 200 status code to confirm callback received
  res.status(200).json({ status: 'received' });
});

app.listen(3000, () => {
  console.log('Callback server running on port 3000');
});
```
```

--------------------------------

### Python Callback Example

Source: https://docs.kie.ai/flux-kontext-api/generate-or-edit-image-callbacks

Example Python (Flask) server that receives the callback, logs the status, and downloads the generated image on success.

```APIDOC
## Python Callback Example

### Description
Example code for receiving Flux image generation callbacks in Python using Flask. It handles the callback payload, logs the status, and downloads the generated image when successful.

### Method
POST

### Endpoint
`/flux-image-callback`

### Request Body
Same as the callback payload described above.

### Response
Returns a 200 status with JSON `{ status: 'received' }` to confirm receipt.

### Code Example
```python
from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)

@app.route('/flux-image-callback', methods=['POST'])
def handle_callback():
    data = request.json
    
    code = data.get('code')
    msg = data.get('msg')
    callback_data = data.get('data', {})
    task_id = callback_data.get('taskId')
    info = callback_data.get('info', {})
    result_image_url = info.get('resultImageUrl')
    
    print(f"Received Flux image generation callback:")
    print(f"Task ID: {task_id}")
    print(f"Status: {code}, Message: {msg}")
    
    if code == 200:
        # Task completed successfully
        print("Flux image generation completed successfully")
        
        print(f"Generated Image URL: {result_image_url}")
        
        # Download generated image
        if result_image_url:
            try:
                result_filename = f"flux_result_{task_id}.jpg"
                download_file(result_image_url, result_filename)
                print(f"Generated image downloaded as {result_filename}")
            except Exception as e:
                print(f"Generated image download failed: {e}")
```
```

--------------------------------

### PHP Callback Reception Example

Source: https://docs.kie.ai/suno-api/suno-voice-validate-callback

Example PHP script that receives the callback and logs the validation phrase status.

```APIDOC
## PHP Callback Reception Example

### Description
Example code for receiving callbacks in PHP.

### Code
```php
<?php
header('Content-Type: application/json');

$input = file_get_contents('php://input');
$payload = json_decode($input, true);

$code = $payload['code'] ?? null;
$msg = $payload['msg'] ?? '';
$data = $payload['data'] ?? [];

$taskId = $data['taskId'] ?? '';
$status = $data['status'] ?? '';
$validateInfo = $data['validateInfo'] ?? '';
$errorMessage = $data['errorMessage'] ?? '';

error_log("Received Suno Voice validation phrase callback: $taskId, status: $status");

if ($code === 200 && $status === 'wait_validating') {
    error_log("Validation phrase is ready: $validateInfo");
} else {
    error_log("Validation phrase generation failed: " . ($errorMessage ?: $msg));
}

http_response_code(200);
echo json_encode(['status' => 'received']);
?>
```
```

--------------------------------

### Download URL Response Example

Source: https://docs.kie.ai/common-api/quickstart

Example response for the download URL endpoint. The data field contains the temporary download link.

```json
{
  "code": 200,
  "msg": "success",
  "data": "https://tempfile.1f6cxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxbd98"
}
```

--------------------------------

### Node.js Callback Example

Source: https://docs.kie.ai/flux-kontext-api/generate-or-edit-image-callbacks

Example Node.js (Express) server that receives the callback, logs the status, and downloads the generated image on success.

```APIDOC
## Node.js Callback Example

### Description
Example code for receiving Flux image generation callbacks in Node.js using Express. It handles the callback payload, logs the status, and downloads the generated image when successful.

### Method
POST

### Endpoint
`/flux-image-callback`

### Request Body
Same as the callback payload described above.

### Response
Returns a 200 status with JSON `{ status: 'received' }` to confirm receipt.

### Code Example
```javascript
const express = require('express');
const fs = require('fs');
const https = require('https');
const app = express();

app.use(express.json());

app.post('/flux-image-callback', (req, res) => {
  const { code, msg, data } = req.body;
  
  console.log('Received Flux image generation callback:', {
    taskId: data.taskId,
    status: code,
    message: msg
  });
  
  if (code === 200) {
    // Task completed successfully
    console.log('Flux image generation completed successfully');
    
    const { taskId, info } = data;
    const { resultImageUrl } = info;
    
    console.log(`Generated Image URL: ${resultImageUrl}`);
    
    // Download generated image
    if (resultImageUrl) {
      downloadFile(resultImageUrl, `flux_result_${taskId}.jpg`)
        .then(() => console.log('Generated image downloaded successfully'))
        .catch(err => console.error('Generated image download failed:', err));
    }

    
  } else {
    // Task failed
    console.log('Flux image generation failed:', msg);
    
    // Handle specific error types
    if (code === 400) {
      console.log('Content policy violation - please adjust prompt');
    } else if (code === 500) {
      console.log('Internal error - please try again later');
    } else if (code === 501) {
      console.log('Generation task failed - may need to adjust parameters');
    }
  }
  
  // Return 200 status code to confirm callback received
  res.status(200).json({ status: 'received' });
});

// Helper function to download files
function downloadFile(url, filename) {
  return new Promise((resolve, reject) => {
    const file = fs.createWriteStream(filename);
    
    https.get(url, (response) => {
      if (response.statusCode === 200) {
        response.pipe(file);
        file.on('finish', () => {
          file.close();
          resolve();
        });
      } else {
        reject(new Error(`HTTP ${response.statusCode}`));
      }
    }).on('error', reject);
  });
}

app.listen(3000, () => {
  console.log('Callback server running on port 3000');
});
```
```

--------------------------------

### Get Remaining Credits Request Example

Source: https://docs.kie.ai/common-api/get-account-credits

Example cURL command to retrieve the current credit balance. Requires a Bearer token in the Authorization header.

```shell
curl --location 'https://api.kie.ai/api/v1/chat/credit' \
--header 'Authorization: Bearer <token>'
```

--------------------------------

### Get Download URL Request with cURL

Source: https://docs.kie.ai/common-api/download-url

Example request to the /api/v1/common/download-url endpoint using cURL.

```bash
curl --location 'https://api.kie.ai/api/v1/common/download-url' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "url": "https://tempfile.aiquickdraw.com/path/to/image.jpg"
}'
```

--------------------------------

### Batch File Upload Usage Example

Source: https://docs.kie.ai/file-upload-api/quickstart

Demonstrates how to initialize the FileUploadAPI and perform batch uploads for both local files and remote URLs.

```python
# Usage example
def main():
    uploader = FileUploadAPI('YOUR_API_KEY')
    
    # Batch upload local files
    file_paths = [
        '/path/to/file1.jpg',
        '/path/to/file2.png',
        '/path/to/document.pdf'
    ]
    
    print("Starting batch file upload...")
    for i, file_path in enumerate(file_paths):
        try:
            result = uploader.upload_file(
                file_path, 
                'user-uploads', 
                f'file-{i + 1}-{os.path.basename(file_path)}'
            )
            print(f"File {i + 1} upload successful: {result['data']['downloadUrl']}")
        except Exception as e:
            print(f"File {i + 1} upload failed: {e}")
    
    # Batch upload from URLs
    urls = [
        'https://example.com/image1.jpg',
        'https://example.com/image2.png'
    ]
    
    print("\nStarting batch URL upload...")
    for i, url in enumerate(urls):
        try:
            result = uploader.upload_from_url(
                url, 
                'downloads', 
                f'download-{i + 1}.jpg'
            )
            print(f"URL {i + 1} upload successful: {result['data']['downloadUrl']}")
        except Exception as e:
            print(f"URL {i + 1} upload failed: {e}")

if __name__ == '__main__':
    main()
```

--------------------------------

### Success Callback JSON Example

Source: https://docs.kie.ai/suno-api/generate-midi-callbacks

Example of the callback payload sent when MIDI generation succeeds. Contains code 200, message 'success', and data with taskId and instruments array with notes (pitch, start, end, velocity).

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e",
    "instruments": [
      {
        "name": "Drums",
        "notes": [
          {
            "pitch": 73,
            "start": 0.036458333333333336,
            "end": 0.18229166666666666,
            "velocity": 1
          },
          {
            "pitch": 61,
            "start": 0.046875,
            "end": 0.19270833333333334,
            "velocity": 1
          },
          {
            "pitch": 73,
            "start": 0.1875,
            "end": 0.4895833333333333,
            "velocity": 1
          }
        ]
      },
      {
        "name": "Electric Bass (finger)",
        "notes": [
          {
            "pitch": 44,
            "start": 7.6875,
            "end": 7.911458333333333,
            "velocity": 1
          },
          {
            "pitch": 56,
            "start": 7.6875,
            "end": 7.911458333333333,
            "velocity": 1
          },
          {
            "pitch": 51,
            "start": 7.6875,
            "end": 7.911458333333333,
            "velocity": 1
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Get Remaining Credits Successful Response

Source: https://docs.kie.ai/common-api/get-account-credits

Example JSON response returned upon a successful request, containing the credit balance in the data field.

```json
{
    "code": 200,
    "msg": "success",
    "data": 100.5
}
```

--------------------------------

### Callback Reception Example (Node.js)

Source: https://docs.kie.ai/runway-api/extend-ai-video-callbacks

Example Node.js Express server that receives the Extend AI Video callback, processes the result, and returns a 200 confirmation.

```APIDOC
## POST /runway-extend-callback

### Description
Receives the asynchronous callback from the Runway Extend AI Video API. The callback contains the task status and result. The server must respond with a 200 status to acknowledge receipt.

### Method
POST

### Endpoint
/runway-extend-callback

### Parameters
#### Request Body
- **code** (integer) - Required - `200` = success, `501` = failed
- **msg** (string) - Required - Status message
- **data.taskId** (string) - Required - Task ID returned when the task was submitted
- **data.model** (string) - Required - Model used for the task (`runway/extend-ai-video`)
- **data.state** (string) - Required - `success` or `fail`
- **data.param** (string) - Required - Parameters submitted when creating the task, as a JSON string
- **data.resultJson** (string) - Optional - Result as a JSON string, e.g. `{"resultUrls":["https://...mp4"]}`. Present on success
- **data.failCode** (string) - Optional - Failure code. Present on failure
- **data.failMsg** (string) - Optional - Failure reason. Present on failure
- **data.costTime** (integer) - Required - Task duration in seconds
- **data.creditsConsumed** (number) - Required - Credits consumed by the task
- **data.createTime** (integer) - Required - Unix timestamp in milliseconds
- **data.completeTime** (integer) - Required - Unix timestamp in milliseconds
- **data.updateTime** (integer) - Required - Unix timestamp in milliseconds

### Request Example
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "12345",
    "model": "runway/extend-ai-video",
    "state": "success",
    "param": "{\"prompt\":\"...\"}",
    "resultJson": "{\"resultUrls\":[\"https://...mp4\"]}",
    "costTime": 30,
    "creditsConsumed": 10,
    "createTime": 1700000000000,
    "completeTime": 1700000030000,
    "updateTime": 1700000030000
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Confirmation message, e.g. `received`

#### Response Example
```json
{
  "status": "received"
}
```
```

--------------------------------

### Install Claude Code on Windows

Source: https://docs.kie.ai/market/chat/claude-code-integration

Run this command in PowerShell to install Claude Code on Windows. After installation, verify with `claude --version`.

```powershell
irm https://claude.ai/install.ps1 | iex
```

--------------------------------

### API Request Example with Image and Tools

Source: https://docs.kie.ai/market/gemini/gemini-3-pro

A complete request example including user messages with an image URL, function tools, streaming, reasoning effort, and structured output format.

```json
{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is in this image?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://file.aiquickdraw.com/custom-page/akr/section-images/1759055072437dqlsclj2.png"
          }
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "googleSearch"
      }
    }
  ],
  "stream": true,
  "include_thoughts": true,
  "reasoning_effort": "high",
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "structured_output",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "response": {
            "type": "string"
          }
        },
        "required": [
          "response"
        ]
      }
    }
  }
}
```

--------------------------------

### Install Claude Code on Mac

Source: https://docs.kie.ai/market/chat/claude-code-integration

Run this command in Terminal to install Claude Code on macOS. After installation, verify with `claude --version`.

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

--------------------------------

### Callback Example for WAV Generation

Source: https://docs.kie.ai/suno-api/convert-to-wav

Example JSON payload sent to the callback URL when WAV audio generation is complete. Contains a success code, message, and data with the audio URL and task ID.

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "audio_wav_url": "https://example.com/s/04e6****e727.wav",
    "task_id": "988e****c8d3"
  }
}
```

--------------------------------

### Install kie-chat-agents with npx

Source: https://docs.kie.ai/ai-agent/install-kie-chat-agents

Run this command to install the kie-chat-agents skill. After installation, you can ask your agent to configure itself, or configure manually using the pages below.

```bash
npx skills add https://kie.ai
```

--------------------------------

### Function Calling with Kimi K3

Source: https://docs.kie.ai/market/kimi/kimi-k3

Demonstrates how to use tools (function calling) with the Kimi K3 model. The model can call functions and receive their outputs.

```APIDOC
## Function Calling

### Description
Use the `tools` parameter to define functions the model can call. The model returns function calls in the response, and you can provide function results back in the input.

### Request Example
```json
{
  "model": "kimi-k3",
  "stream": false,
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Get the current weather for a city",
      "parameters": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "City name" }
        },
        "required": ["city"],
        "additionalProperties": false
      }
    }
  ],
  "input": [
    { "role": "user", "content": "What's the weather like in Beijing right now?" },
    {
      "type": "function_call",
      "call_id": "call_6102a526bdda4ebf8e982aa3",
      "name": "get_weather",
      "arguments": "{\"city\":\"Beijing\"}"
    },
    {
      "type": "function_call_output",
      "call_id": "call_6102a526bdda4ebf8e982aa3",
      "output": "{\"temp_c\":21,\"condition\":\"sunny\"}"
    }
  ]
}
```
```

--------------------------------

### Example Webhook Request

Source: https://docs.kie.ai/common-api/webhook-verification

Example of a webhook request sent by the API.

```APIDOC
## Example Webhook Request

### Description
Example of a webhook request sent by the API.

### Request
Not specified in source.
```
Tokens:
Raw