Surgepix API Reference

Base URL: https://api.surgepix.ai/api

All requests must include the authorization header:

authorization: sk-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

All responses follow the CommonResult structure. code=0 indicates success; any other value indicates failure.

Async Task Model

Background removal is asynchronous by default. The API returns a taskId, and you poll for the result:

GET /tasks/{taskId}

Alternatively, set noWait=true to enable synchronous mode — the API will wait for the task to complete before returning.

Task progress values (progress field):

• processing — Task is currently running
• succeeded — Task completed; result is in taskResult
• failed — Task failed

Task status is retained for 24 hours. Queries after expiration return 404.

Sessions

Each API call can be associated with a session, grouping multiple iterations together (viewable in the platform UI). If sessionId is not provided, the platform automatically creates a new session and returns it in the response.

To iterate on a previous result, pass the sessionId from the last response — both results will appear in the same session history.

Core Concepts

File Upload

• Files are uploaded via a chunked upload flow (/upload/chat-init → /upload/chunk → /upload/chat-complete)
• On completion, a publicly accessible file URL is returned as input for the background removal task
• Supported image formats: jpeg, jpg, png, webp, gif
• Image files undergo NSFW content detection during upload

Task (taskId)

• Created when calling the remove-background endpoint
• Represents one processing operation; state transitions: processing → succeeded / failed
• On success, taskResult contains the download link
• Each task belongs to exactly one session

Output (Download Link)

• A transparent .png file with the background removed
• Returned as taskResult.download on task success

Session (sessionId)

• Groups multiple tasks (iteration history) for the same request
• If sessionId is omitted on first call, the platform creates one automatically
• Pass the same sessionId on subsequent calls to append tasks to the same session

Object Relationship Overview:

Session (1)
 └── Task (many)  ←── File URL (obtained via chunked upload)
      └── Output (1 transparent PNG, on success)

Endpoints

Chunked Upload

Used to upload images to Tencent Cloud COS. Flow: Initialize → Upload Chunks → Complete.

1. Initialize Chunked Upload

Path: POST /upload/chat-init

Query Parameters:

Response Example:

{
  "code" 0,
  "message": "success",
  "data": {
    "uploadId": "abc123xyz",
    "url": null,
    "filename": "example.png",
    "size": null,
    "contentType": null
  }
}

If url is not null in the response, the file was previously uploaded. Use that URL directly — no need to upload chunks.

2. Upload Chunk

Path: POST /upload/chunk

Form-Data Parameters:

Response Fields:

Response Example:

{
  "code": 0,
  "message": "success",
  "data": {
    "partNumber": 1,
    "eTag": "\"d41d8cd98f00b204e9800998ecf8427e\""
  }
}

3. Complete Chunked Upload

Path: POST /upload/chat-complete

Query Parameters:

Request Body (JSON):

[
  { "partNumber": 1, "eTag": "\"d41d8cd98f00b204e9800998ecf8427e\"" },
  { "partNumber": 2, "eTag": "\"098f6bcd4621d373cade4e832627b4f6\"" }
]

Response Fields:

Response Example:

{
  "code": 0,
  "message": "success",
  "data": {
    "uploadId": null,
    "url": "https://surgepix-1316642525.cos.ap-seoul.myqcloud.com/uploads/files/example.png",
    "filename": "example.png",
    "size": 4905017,
    "contentType": "image/png"
  }
}

Image files (jpg/jpeg/png/webp/gif) undergo NSFW content detection during upload. Sensitive content will result in an error.

Chunked Upload Flow Summary

1. Initialize: Call POST /upload/chat-init with file name and MD5 to get uploadId
2. Upload chunks: Split the file into chunks (recommended 5MB each), upload each via POST /upload/chunk, and record the returned partNumber and eTag
3. Complete: After all chunks are uploaded, call POST /upload/chat-complete with uploadId and the list of ETags
4. Get result: On success, the response contains the complete file URL for use in subsequent API calls

POST /tasks/remove-background

Submit a background removal task for a specified image URL.

Content-Type: application/json

Request Parameters:

Request Example:

{
  "fileUrl": "https://surgepix-1316642525.cos.ap-seoul.myqcloud.com/uploads/files/example.png",
  "sessionId": 123,
  "noWait": false
}

Response Example (async mode, noWait=false):

{
  "code": 0,
  "data": {
    "taskId": "task_a1b2c3d4e5f6",
    "sessionId": 123,
    "progress": "processing",
    "taskResult": null
  },
  "msg": ""
}

Response Example (sync mode, noWait=true, success):

{
  "code": 0,
  "data": {
    "taskId": "task_a1b2c3d4e5f6",
    "sessionId": 123,
    "progress": "succeeded",
    "taskResult": {
      "download": "https://surgepix-ai-1316642525.cos.ap-seoul.myqcloud.com/test/images/download/result_no_bg.png"
    }
  },
  "msg": ""
}

Output is always in .png format to preserve transparency.

GET /tasks/{taskId}

Query the current progress and result of an async task.

Path Parameters:

Response Fields:

Response Example (processing):

{
  "code": 0,
  "data": {
    "taskId": "task_a1b2c3d4e5f6",
    "sessionId": 123,
    "progress": "processing",
    "taskResult": null
  },
  "msg": ""
}

Response Example (succeeded):

{
  "code": 0,
  "data": {
    "taskId": "task_a1b2c3d4e5f6",
    "sessionId": 123,
    "progress": "succeeded",
    "taskResult": {
      "download": "https://surgepix-ai-1316642525.cos.ap-seoul.myqcloud.com/test/images/download/result_no_bg.png"
    }
  },
  "msg": ""
}

Response Example (task not found):

{
  "code": 404,
  "data": null,
  "msg": "Task not found"
}

Error Handling

Unified Response Structure:

All endpoint responses follow the CommonResult structure:

{
  "code": 0,
  "data": { ... },
  "msg": ""
}

• code=0: Request successful
• code≠0: Request failed; error details in the msg field

Common Errors:

Upload-Related Errors:

Typical Workflow

Async Mode (Recommended)

1. Upload image: Obtain the image URL via the chunked upload flow
2. Submit task: POST /tasks/remove-background (noWait=false), get taskId
3. Poll status: GET /tasks/{taskId} until progress is succeeded or failed
4. Get result: Retrieve the background-removed image from taskResult.download

Sync Mode

1. Upload image: Obtain the image URL via the chunked upload flow
2. Submit and wait: POST /tasks/remove-background (noWait=true), wait for the response with the final result

Quick Reference