API Documentation

Integrate NeoSpark's AI image and video generation capabilities into your application. Build creative workflows with a simple, powerful REST API.

Overview

Base URL

https://api.useneospark.com/api/v1

NeoSpark provides two core API modules: Image Generation and Seedance 2.0 Video Generation. Both support API Key authentication and follow RESTful conventions with JSON request/response formats.

Authentication

All API requests require authentication. We support two methods:

Method 1: X-API-Key Header (Recommended)

curl "https://api.useneospark.com/api/v1/drawing/models/config" \
  -H "X-API-Key: np_your_api_key_here"

Method 2: Authorization Header

curl "https://api.useneospark.com/api/v1/drawing/models/config" \
  -H "Authorization: ApiKey np_your_api_key_here"

Bearer Token (Temporary Access)

curl "https://api.useneospark.com/api/v1/drawing/models/config" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Getting an API Key

  1. Visit platform.useneospark.com
  2. Sign in with Google OAuth
  3. Navigate to User Settings → API Keys
  4. Click "Create API Key"
  5. Copy the generated key (shown only once)

Image Generation API

Support for text-to-image, image-to-image, and multi-reference generation via Google Gemini and Tengda (MagicAPI) providers.

Supported Models & Pricing

Model Provider Resolution Multi-Ref Price (Credits)
gemini-3-pro-image-preview gemini 1K, 2K, 4K Up to 14 1K=13, 2K=13, 4K=18
gemini-3.1-flash-image-preview gemini 512, 1K, 2K, 4K Up to 14 512=4, 1K=7, 2K=7, 4K=13
gemini-2.5-flash-image gemini 1K Single 1K=6
gemini-2.5-flash-image gemini 1K Single 6
gpt-image-2 openai 512, 1K, 2K, 4K Yes 1K_std=4, 1K_hd=7

1. Get Model Config

Retrieve available models with pricing and supported resolutions.

GET /drawing/models/config

2. Create Session

Create a drawing session. Reuse the same session_id for related generations.

POST /drawing/sessions 
{"title": "My Creation"}

3. Generate Image

Submit a generation task (text-to-image or image-to-image).

POST /drawing/sessions/{session_id}/generate 
{"prompt": "A cute cat on a windowsill, sunlight, healing illustration style",
  "model": "gemini-3.1-flash-image-preview",
  "resolution": "1K",
  "aspect_ratio": "1:1",
  "num_images": 1,
  "provider": "gemini",
  "optimize_prompt": true
}

Key Parameters:

  • prompt (string, required) — Description of the image
  • model (string, required) — Model ID
  • resolution (string, required) — 512 / 1K / 2K / 3K / 4K
  • aspect_ratio (string, required) — 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / etc.
  • num_images (int, optional) — 1-4, default 1
  • negative_prompt (string, optional) — Elements to avoid
  • ref_upload_id (string, optional) — Single reference image upload ID
  • ref_upload_ids (string[], optional) — Multiple reference image IDs (up to 14)
  • ref_image_paths (string[], optional) — Reference generated image URLs
  • strength (float, optional) — Reference strength 0.0-1.0, default 0.7
  • provider (string, optional) — gemini or openai, default gemini
  • quality (string, optional) — standard or high (gpt-image-2 only)

4. Check Generation Status

Poll for generation result by message_id.

GET /drawing/messages/{message_id} 
// Response (completed)
{
  "code": 200,
  "data": {
    "message_id": "dm_a1b2c3d4e5_assistant",
    "status": "completed",
    "images": [
      {"url": "/uploads/3/images/2026/04/23/generated_0.png"}
    ],
    "actual_cost": 7
  }
}

5. Upload Reference Image

Upload an image for use as a reference in image-to-image generation.

POST /storage/upload 
// multipart/form-data
file: <binary>
file_type: image

6. List User Images

Get all uploaded and generated images for the current user.

GET /storage/user-images?limit=20

7. Get Billing History

Retrieve credit transaction history for drawing operations.

GET /drawing/billing/history?limit=20

Image Generation Flow

  1. Create a drawing session via POST /drawing/sessions
  2. Submit generation task via POST /drawing/sessions/{id}/generate
  3. Poll status via GET /drawing/messages/{message_id}
  4. Retrieve completed image URL from the response

Seedance 2.0 Video Generation API

Generate AI videos via an asynchronous task-based workflow. Supports text-to-video, image-to-video, and reference-based generation.

Supported Models & Pricing

Model Description Price (Credits/sec)
AiVideoMax Highest quality, cinematic output 26
AiVideoMin Balanced cost and speed 21

Supported Parameters

Parameter Type Required Description
prompt string Yes Video description (1-2000 chars)
model string No AiVideoMax (default) or AiVideoMin
duration int No 4-15 seconds, default 5
ratio string No 16:9 (default), 9:16, 1:1, 4:3, 3:4, 21:9
resolution string No 720p (default) or 480p
generate_audio bool No Generate audio, default false
first_frame_url string No Image URL for image-to-video
reference_image_urls string[] No Reference images, max 9
reference_video_urls string[] No Reference videos, max 3
reference_audio_url string No Reference audio for style/rhythm

1. Create Video Task

POST /video/generations 
{"prompt": "A cute corgi running on the beach at sunset",
  "model": "AiVideoMax",
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720p",
  "generate_audio": false
}

2. Check Task Status

GET /video/generations/{task_id} 
// Response (completed)
{
  "code": 200,
  "data": {
    "task_id": "video_a1b2c3d4e5f6",
    "status": "completed",
    "progress": 100,
    "video_url": "/uploads/videos/1/video_a1b2c3d4e5f6.mp4",
    "actual_cost": 130
  }
}

3. List Video Tasks

GET /video/generations?page=1&page_size=20

4. Delete Video Task

DELETE /video/generations/{task_id}

5. Get Video Models

GET /video/models

Video Generation Flow

  1. Submit task via POST /video/generations → receive task_id
  2. Poll status via GET /video/generations/{task_id} every 2-5 seconds
  3. When status becomes "completed", retrieve video_url
  4. Download or use the video URL directly

Error Handling

HTTP Code Meaning Resolution
200 Success —
400 Invalid parameters Check parameter format and ranges
401 Invalid or expired API Key Verify API Key and regenerate if needed
402 Insufficient credits Recharge or upgrade your plan
404 Task/session not found Verify task_id or session_id
500 Internal server error Retry after a short delay
502 External service error Check resource URL accessibility

Error Response Format

{
  "code": 402,
  "message": "Insufficient credits. Available: 50, Required: 130",
  "data": null
}

Best Practices

1. API Key Security

Never hardcode API Keys in frontend code. Use environment variables or server-side proxies. 

// Good
const API_KEY = process.env.NEOSPARK_API_KEY;

// Bad
const API_KEY = "np_xxxxxxxxxxxxx";

2. Polling Strategy

Poll every 2-5 seconds with a maximum timeout of 5 minutes (60 attempts). Implement exponential backoff for better efficiency.

3. Credit Estimation

Check user balance before expensive operations. The estimated_cost field is returned when creating a task. 

# Video cost formula
cost = price_per_second × duration

# Image cost formula
cost = unit_price × num_images

4. Session Management

Reuse drawing sessions for related generations. This improves organization and allows better history tracking. Delete completed sessions when no longer needed.

Start Building

Get your API Key and start integrating AI-powered image and video generation into your application today.

Get API Key