SJinn
Tool API

Tool API

Directly invoke AI tools to generate videos and images with Veo3, Sora2, Grok, Seedream, Nano Banana, Nano Banana 2, and more

Tool API Overview

The Tool API provides direct access to specific AI tools on the SJinn platform. Unlike the Agent API which automatically plans and executes, the Tool API gives you precise control over which model and parameters to use.

Supported Tools

Video Generation

Lip-Sync

  • Image Lipsync — image-lipsync-api — audio_seconds × 30 credits

Image Generation

Click each tool name for detailed parameters and examples.

Create Tool Task

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

Parameters

  • tool_type (string, required) - Tool identifier from the tables above
  • input (object, required) - Tool-specific parameters (see individual tool docs)

All image URLs in input must be complete HTTP/HTTPS addresses. Relative paths are not supported.

Request Example

{
  "tool_type": "veo3-text-to-video-fast-api",
  "input": {
    "prompt": "A majestic dragon flying through clouds at sunset",
    "aspect_ratio": "16:9"
  }
}

Success Response

{
  "success": true,
  "errorMsg": "",
  "error_code": 0,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Query Task Status

Supports both POST and GET methods.

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

GET /api/un-api/query_tool_task_status?task_id=YOUR_TASK_ID
Authorization: Bearer YOUR_API_KEY

Parameters

  • task_id (string, required) - Task ID returned from create_tool_task

Success Response

{
  "success": true,
  "errorMsg": "",
  "error_code": 0,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "task_type": "veo3-text-to-video-fast-api",
    "status": 1,
    "output_urls": [
      "https://cdn.sjinn.ai/videos/output_video.mp4"
    ],
    "input": {
      "prompt": "A serene sunset over the ocean",
      "aspect_ratio": "16:9"
    },
    "create_time": "2024-01-15T10:30:00Z",
    "update_time": "2024-01-15T10:35:00Z"
  }
}

Task Status Codes

  • 0 - Initializing/Processing
  • 1 - Completed
  • -1 - Failed

Complete Workflow Example

JavaScript

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

async function createTask(toolType, input) {
  const response = await fetch(`${BASE_URL}/create_tool_task`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ tool_type: toolType, input }),
  });
  
  const result = await response.json();
  if (!result.success) throw new Error(result.errorMsg);
  return result.data.task_id;
}

async function waitForCompletion(taskId, maxAttempts = 60) {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(`${BASE_URL}/query_tool_task_status`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ task_id: taskId }),
    });
    
    const result = await response.json();
    
    if (result.data.status === 1) return result.data;
    if (result.data.status === -1) throw new Error(result.data.error || 'Task failed');
    
    console.log(`Processing... (${i + 1}/${maxAttempts})`);
    await new Promise(resolve => setTimeout(resolve, 10000));
  }
  throw new Error('Timeout waiting for task completion');
}

// Usage
const taskId = await createTask('veo3-text-to-video-fast-api', {
  prompt: 'A cinematic shot of a dragon flying over mountains',
  aspect_ratio: '16:9',
});
const result = await waitForCompletion(taskId);
console.log('Output:', result.output_urls[0]);

Python

import requests
import time

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

def create_task(tool_type, input_data):
    response = requests.post(
        f'{BASE_URL}/create_tool_task',
        json={'tool_type': tool_type, 'input': input_data},
        headers={'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'}
    )
    result = response.json()
    if not result['success']:
        raise Exception(result['errorMsg'])
    return result['data']['task_id']

def wait_for_completion(task_id, max_attempts=60):
    for i in range(max_attempts):
        response = requests.post(
            f'{BASE_URL}/query_tool_task_status',
            json={'task_id': task_id},
            headers={'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'}
        )
        result = response.json()
        
        if result['data']['status'] == 1:
            return result['data']
        elif result['data']['status'] == -1:
            raise Exception(result['data'].get('error', 'Task failed'))
        
        print(f'Processing... ({i + 1}/{max_attempts})')
        time.sleep(10)
    raise Exception('Timeout waiting for task completion')

# Usage
task_id = create_task('nano-banana-image-pro-api', {
    'prompt': 'A breathtaking landscape of northern lights over snowy mountains',
    'aspect_ratio': '16:9',
    'resolution': '2K'
})
result = wait_for_completion(task_id)
print(f'Output: {result["output_urls"][0]}')

Error Codes

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

Error response format:

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

Best Practices

  • Polling interval: Video/Lip-Sync tasks every 10-15s (2-10 min typical), Image tasks every 5-10s (10-90s typical). Set a 10-15 minute timeout.
  • Error handling: Always check the success field. Credits are automatically refunded on task failure.
  • Cost optimization: Use Std mode for prototyping, switch to Pro/high-res after confirming results.
  • Reliability: Save task_id immediately, implement retry logic, and control concurrency for batch tasks.
  • Rate limits: Concurrent task limits depend on your subscription plan. Consider implementing a request queue.

Related Links

  • Agent API - AI Agent for automatic task planning and execution
  • Get API Key - Obtain and manage API keys