SJinn
Agent API

Agent API

Create and manage AI Agent tasks through the SJinn API.

Agent API Overview

The Agent API allows you to create AI-powered tasks that can automatically generate videos, images, and more through intelligent planning and execution.

Create Agent Task

Start a new AI Agent task with a text prompt.

Request

POST /api/un-api/create_agent_task
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Parameters

  • message (string, required) - The task description for the AI Agent
  • template_id (string, optional) - Template ID from https://sjinn.ai/templates for guided task execution, e.g. "788acc9a-866b-4688-849e-7c7cfffaff54"

Example Request

{
  "message": "Create a video of a cute panda playing with bubbles in a bamboo forest",
  "template_id": "788acc9a-866b-4688-849e-7c7cfffaff54"
}

Example with cURL

curl -X POST https://sjinn.ai/api/un-api/create_agent_task \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Create a video of a cute panda playing with bubbles"
  }'

Example with JavaScript

const response = await fetch('https://sjinn.ai/api/un-api/create_agent_task', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: 'Create a video of a cute panda playing with bubbles',
    template_id: '788acc9a-866b-4688-849e-7c7cfffaff54',
  }),
});

const result = await response.json();
console.log(result);

Success Response

{
  "success": true,
  "errorMsg": "",
  "error_code": 0,
  "data": {
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "chat_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  }
}

Response Fields

  • success (boolean) - Whether the request was successful
  • errorMsg (string) - Error message if failed
  • error_code (number) - Error code (0 for success)
  • data.project_id (string) - Unique project identifier
  • data.chat_id (string) - Unique chat/task identifier for status queries

Query Agent Task Status

Check the status and results of an Agent task.

Request

POST Method:

POST /api/un-api/query_agent_task_status
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

GET Method:

GET /api/un-api/query_agent_task_status?chat_id=YOUR_CHAT_ID&tool_names=tool1,tool2
Authorization: Bearer YOUR_API_KEY

Parameters

  • chat_id (string, required) - The chat ID returned from create_agent_task
  • tool_names (string[], optional) - Filter results to only include specified tools. Recommended: ["ffmpeg_full_compose"] to get the final composed video

Example Request (POST)

{
  "chat_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "tool_names": ["SJinn_Image_Edit", "Kling_Image_to_Video", "ffmpeg_full_compose"]
}

Example Request (GET)

curl -X GET "https://sjinn.ai/api/un-api/query_agent_task_status?chat_id=6ba7b810-9dad-11d1-80b4-00c04fd430c8&tool_names=SJinn_Image_Edit,ffmpeg_full_compose" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example with JavaScript

// Query all tool results
const response = await fetch('https://sjinn.ai/api/un-api/query_agent_task_status', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    chat_id: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
  }),
});

// Query specific tool results only
const filteredResponse = await fetch('https://sjinn.ai/api/un-api/query_agent_task_status', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    chat_id: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
    tool_names: ['ffmpeg_full_compose'],  // Only get final video results
  }),
});

Success Response

{
  "success": true,
  "errorMsg": "",
  "error_code": 0,
  "data": {
    "chat_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": 1,
    "tool_results": [
      {
        "name": "ffmpeg_full_compose",
        "result": ["https://cdn.sjinn.ai/composed_videos/final_video.mp4"]
      }
    ],
    "create_time": "2024-01-15T10:30:00Z",
    "update_time": "2024-01-15T10:35:00Z"
  }
}

Response Fields

  • success (boolean) - Whether the request was successful
  • data.chat_id (string) - The chat/task identifier
  • data.project_id (string) - The project identifier
  • data.status (number) - Task status code
  • data.tool_results (array) - Array of tool execution results
  • data.tool_results[].name (string) - Name of the tool that was executed
  • data.tool_results[].result (array) - Array containing the tool's output URLs
  • data.create_time (string) - Task creation timestamp
  • data.update_time (string) - Last update timestamp

Status Values

  • 1 - Task not started or completed
  • 2 - Task is running

Common Tool Names

  • ffmpeg_full_compose - Recommended - Compose multiple videos into final output. The final video URL is typically returned here
  • Image_VQA - Image analysis and understanding
  • SJinn_Image_Edit - AI image generation and editing
  • Kling_Image_to_Video - Convert image to video
  • TODO_Write - Task planning output

Complete Workflow Example

Here's a complete example of creating a task and polling for results:

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://sjinn.ai/api/un-api';

// Step 1: Create the task
async function createTask(message) {
  const response = await fetch(`${BASE_URL}/create_agent_task`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ message }),
  });
  
  const result = await response.json();
  if (!result.success) {
    throw new Error(result.errorMsg);
  }
  return result.data;
}

// Step 2: Poll for status
async function waitForCompletion(chatId, maxAttempts = 200) {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(`${BASE_URL}/query_agent_task_status`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        chat_id: chatId,
        tool_names: ['ffmpeg_full_compose'],  // Recommended: get final composed video
      }),
    });
    
    const result = await response.json();
    
    // status: 1 = not started or completed, 2 = running
    if (result.data.status === 1 && result.data.tool_results.length > 0) {
      // Task completed with results
      return result.data;
    }
    
    if (result.data.status === 2) {
      // Task still running, continue polling
      console.log('Task is running...');
    }
    
    // Wait 5 seconds before next poll
    await new Promise(resolve => setTimeout(resolve, 30000));
  }
  
  throw new Error('Timeout waiting for task completion');
}

// Usage
async function main() {
  try {
    const { chat_id, project_id } = await createTask(
      'Create a cinematic video of a dragon flying over mountains at sunset'
    );
    
    console.log('Task created:', { chat_id, project_id });
    
    const result = await waitForCompletion(chat_id);
    
    // Get the final video URL
    const videoResult = result.tool_results.find(
      t => t.name === 'ffmpeg_full_compose'
    );
    
    if (videoResult) {
      // result is an array of URLs
      console.log('Final video:', videoResult.result[0]);
    }
  } catch (error) {
    console.error('Error:', error.message);
  }
}

main();

Error Codes

  • 0 - Success
  • 100 - Insufficient balance
  • 101 - Membership required
  • 401 - Invalid or missing access token
  • 403 - Unauthorized access
  • 404 - Resource not found
  • 500 - Internal server error

Error Response Example

{
  "success": false,
  "errorMsg": "Insufficient balance",
  "error_code": 100
}

Rate Limits

  • Agent tasks consume credits based on the tools used
  • Each task requires a minimum of 200 credits
  • Concurrent task limits depend on your subscription plan