📡REST API

API Documentation

Integrate ScholarPlot scientific figure generation into your applications via REST API

🔑 Get Your API Key

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

Parameter	Type	Required	Description
`description`	string	✅	Chart content description
`chartType`	string	❌	Chart type ID (auto-select if omitted)
`language`	string	❌	"zh" \| "en" (default: "en")
`aspectRatio`	string	❌	"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)

💻 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 Status	Code	Description
400	`INVALID_PARAMS`	Missing or invalid parameters
401	`UNAUTHORIZED`	Invalid or missing API key
402	`NO_CREDITS`	Insufficient credits
403	`FORBIDDEN`	No permission to access resource
500	`SERVER_ERROR`	Internal server error