📡REST API

API Documentation

Integrate ScholarPlot scientific figure and marketing material generation into your applications via REST API

🔑 Get Your API Key

Sign in and generate your API Key on the MCP page

Get Key

Base URL

https://figure.thirdme.com/api/v1

🔐 Authentication

All API requests require a Bearer Token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

📡 Endpoints

POST/charts/generate

Create a new scientific figure generation task

Request Body

ParameterTypeRequiredDescription
descriptionstring✅Chart content description
chartTypestring❌Chart type ID (auto-select if omitted)
languagestring❌"zh" | "en" (default: "en")
aspectRatiostring❌"16:9" | "4:3" | "1:1"

Response

{
  "success": true,
  "taskId": "675e8a3b2f1c4d5e6a7b8c9d",
  "status": "generating",
  "creditsRemaining": 48
}
GET/charts/status/:taskId

Check chart generation task status

Completed Response

{
  "taskId": "675e8a3b2f1c4d5e6a7b8c9d",
  "status": "completed",
  "imageUrl": "https://figure.thirdme.com/uploads/sci-figures/xxx.webp",
  "thumbnailUrl": "https://figure.thirdme.com/uploads/sci-figures/xxx-thumb.webp"
}
GET/charts/templates

Get available chart templates (no auth required)

Material Generation API

Base URL: https://figure.thirdme.com/api/material — Each image consumes 1 credit; failed images are refunded

POST/material/generate

Create a material project and generate images in batch (up to 20)

Request Body

ParameterTypeRequiredDescription
promptstring❌*Single description, use with batchCount
promptsstring[]❌*Multiple descriptions, up to 20
batchCountnumber❌Repeat count for single prompt (1-20)
aspectRatiostring❌1:1 | 16:9 | 9:16 | 4:3 | 3:4 | custom
imageSizestring❌1K | 2K | 4K
customWidthPxnumber❌Custom width 256-4096
customHeightPxnumber❌Custom height 256-4096
referenceImagestring❌Reference image base64 data URL

* Either prompt or prompts is required

Response

{
  "success": true,
  "projectId": "675e8a3b2f1c4d5e6a7b8c9d",
  "versionIds": ["675e8a3b2f1c4d5e6a7b8c9e", "675e8a3b2f1c4d5e6a7b8c9f"],
  "generatedCount": 2
}
GET/material/projects/:projectId

Poll material project status until status is not generating

Completed Response

{
  "success": true,
  "project": {
    "id": "675e8a3b2f1c4d5e6a7b8c9d",
    "status": "completed",
    "aspectRatio": "16:9",
    "imageSize": "2K",
    "versions": [
      {
        "slotIndex": 1,
        "status": "completed",
        "imageUrl": "https://figure.thirdme.com/uploads/materials/xxx.webp",
        "thumbnailUrl": "https://figure.thirdme.com/uploads/materials/xxx-thumb.webp"
      }
    ]
  }
}

💻 Code Examples

cURL

curl -X POST https://figure.thirdme.com/api/v1/charts/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "description": "A bar chart comparing sales across Q1-Q4 2024",
    "language": "en"
  }'

Python

import requests
import time

API_KEY = "your_api_key"
BASE_URL = "https://figure.thirdme.com/api/v1"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

# Generate chart
response = requests.post(f"{BASE_URL}/charts/generate", 
    headers=headers,
    json={
        "description": "A pie chart showing market share",
        "language": "en"
    }
)
task_id = response.json()["taskId"]

# Poll for completion
while True:
    status = requests.get(f"{BASE_URL}/charts/status/{task_id}", 
        headers=headers).json()
    
    if status["status"] == "completed":
        print(f"Chart ready: {status['imageUrl']}")
        break
    elif status["status"] == "failed":
        print(f"Failed: {status['error']}")
        break
    
    time.sleep(2)

JavaScript

const API_KEY = 'your_api_key';
const BASE_URL = 'https://figure.thirdme.com/api/v1';

async function generateChart(description, chartType = null) {
  const response = await fetch(`${BASE_URL}/charts/generate`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      description,
      chartType,
      language: 'en'
    })
  });
  
  const { taskId } = await response.json();
  
  // Poll for completion
  while (true) {
    const statusRes = await fetch(`${BASE_URL}/charts/status/${taskId}`, {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    });
    const status = await statusRes.json();
    
    if (status.status === 'completed') return status.imageUrl;
    if (status.status === 'failed') throw new Error(status.error);
    
    await new Promise(r => setTimeout(r, 2000));
  }
}

// Usage
generateChart('A flowchart showing user registration')
  .then(url => console.log('Chart:', url));

⚠️ Error Codes

HTTP StatusCodeDescription
400INVALID_PARAMSMissing or invalid parameters
401UNAUTHORIZEDInvalid or missing API key
402NO_CREDITSInsufficient credits
403FORBIDDENNo permission to access resource
500SERVER_ERRORInternal server error