API documentation

Quick start

Use the website account to activate the API service and create a key. The API uses the asynchronous task protocol:Submit image → Check status → Download SVG. received 202 only means that it has been received, but does not mean that the conversion is completed.

Prepare environment variables

export API_BASE_URL='https://svgo-api.com/openapi/v1'
export API_KEY='YOUR_API_KEY'
# Use one key per business task. Keep it for retries; use a new key for a new image.
export IDEMPOTENCY_KEY='your-business-request-0001'

The keys in the example are placeholders. Each new business task generates a unique idempotent key, and the original key and original image are retained when the original task is retried. Use first GET /capabilities Check acceptsTasks, do not submit images before it is open.

Submit and save the task

curl --fail-with-body -sS "$API_BASE_URL/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -F 'image=@image.png' \
  -o task.json

# Requires jq. Save the taskId from task.json.
TASK_ID=$(jq -r '.taskId // empty' task.json)
cat task.json

{
  "taskId": "6dd39862-bec8-44e4-b72e-50a40618ba6e",
  "status": "queued",
  "errorCode": null,
  "createdAt": "2026-10-28T02:00:00.000Z",
  "finishedAt": null,
  "expiresAt": null,
  "billing": {
    "source": "package",
    "state": "reserved",
    "reservedCents": 0,
    "chargedCents": null,
    "successOrdinal": null
  }
}

Save the response taskId。status=queued means it has entered the queue and do not create the task again. new task responsive Location is the query address, Retry-After It is recommended to wait 3 seconds for the first query; the latest task status shall prevail when querying.

Query and receive results

curl --fail-with-body -sS "$API_BASE_URL/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

# Download only after status=succeeded. The response below is a file, not JSON.
curl --fail -sS "$API_BASE_URL/tasks/$TASK_ID/result" \
  -H "Authorization: Bearer $API_KEY" \
  -o result.svg

It is recommended to query at an interval of 3 seconds (10 seconds in queue). only succeeded can be downloaded;failed、cancelled、expired is an unsuccessful final state.

Authentication and Security

All /openapi/v1 All interfaces are required Authorization: Bearer YOUR_API_KEY. Website cookies, membership status, and URL query parameters are not substitutes for the API Key. Production requests use HTTPS.

The query capability only requires a valid Key. The key created by the console currently contains the above four permissions; subdivided permissions can be configured by the management side. The complete Key is only displayed once when it is created, and a maximum of 20 valid Keys are retained.

• Keys are only stored on your own server or key management system and are not embedded in web pages, extensions, Git repositories or logs.
• Immediately revoke the old Key after leakage, create a replacement Key and update the server configuration; revocation will not revoke the submitted task.
• Multiple Keys in the same account share quota, historical times, queues and dual concurrency, and can query the tasks of the same account.
• Tasks to access other accounts uniformly return 404. Don't try to use the account ID parameter to switch task ownership.

Input and output

Let the client library generate the multipart boundary; do not hardcode Content-Type: multipart/form-data. Choose either file upload or JSON URL input. Extra fields, Base64 input, custom colors, backgrounds and output parameters are not supported.

Complete code examples

The Node.js and Python examples include capabilities checks, uploads, polling, saving results and bounded backoff. Retries after network interruptions keep the original idempotency key and image. A polling timeout is not treated as conversion failure.

export API_BASE_URL='https://svgo-api.com/openapi/v1'
export API_KEY='YOUR_API_KEY'
# Use one key per business task. Keep it for retries; use a new key for a new image.
export IDEMPOTENCY_KEY='your-business-request-0001'

# Confirm acceptsTasks=true first. Capabilities queries are free.
curl --fail-with-body -sS "$API_BASE_URL/capabilities" \
  -H "Authorization: Bearer $API_KEY"

curl --fail-with-body -sS "$API_BASE_URL/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -F 'image=@image.png' \
  -o task.json

# Requires jq. Save the taskId from task.json.
TASK_ID=$(jq -r '.taskId // empty' task.json)
cat task.json

# If not successful yet, poll again after 3 seconds (10 when queued). Do not download or recreate the task.
curl --fail-with-body -sS "$API_BASE_URL/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

# Download only after status=succeeded. The response below is a file, not JSON.
curl --fail -sS "$API_BASE_URL/tasks/$TASK_ID/result" \
  -H "Authorization: Bearer $API_KEY" \
  -o result.svg

Example using curl and jq. If the query is still unsuccessful, continue to wait. Do not regard the last download command as automatic polling.

Interface Reference

The following paths are relative to https://svgo-api.com/openapi/v1. All interfaces are subject to permission verification based on the account to which the Key belongs. Only the download results are returned as files, the rest of the successful responses are JSON.

{
  "taskId": "6dd39862-bec8-44e4-b72e-50a40618ba6e",
  "status": "queued",
  "errorCode": null,
  "createdAt": "2026-10-28T02:00:00.000Z",
  "finishedAt": null,
  "expiresAt": null,
  "billing": {
    "source": "package",
    "state": "reserved",
    "reservedCents": 0,
    "chargedCents": null,
    "successOrdinal": null
  }
}

{
  "taskId": "6dd39862-bec8-44e4-b72e-50a40618ba6e",
  "status": "succeeded",
  "errorCode": null,
  "createdAt": "2026-10-28T02:00:00.000Z",
  "finishedAt": "2026-10-28T02:01:00.000Z",
  "expiresAt": "2026-10-29T02:01:00.000Z",
  "billing": {
    "source": "package",
    "state": "consumed",
    "reservedCents": 0,
    "chargedCents": 0,
    "successOrdinal": "1"
  }
}

{
  "accountId": "6fb13245-5c30-48e4-a5c7-0bfffc34a32f",
  "currency": "CNY",
  "balanceCents": "10000",
  "reservedCents": "20",
  "availableCents": "9980",
  "packageAvailableCalls": "0",
  "packageReservedCalls": "0",
  "lifetimeSuccessCount": "999",
  "nextUnitPriceCents": 20,
  "maxConcurrency": 2,
  "activeTasks": 1,
  "maxPendingTasks": 6,
  "maxGlobalPendingTasks": 18,
  "walletFallback": true
}

{
  "items": [
    {
      "taskId": "6dd39862-bec8-44e4-b72e-50a40618ba6e",
      "successOrdinal": "1001",
      "source": "wallet",
      "chargedCents": 15,
      "consumedPackageCalls": 0,
      "createdAt": "2026-10-28T02:01:00.000Z"
    }
  ],
  "nextCursor": null
}

{
  "version": "v1",
  "acceptsTasks": false,
  "paymentAvailable": false,
  "formats": [
    "png",
    "jpeg",
    "webp"
  ],
  "inputMethods": [
    "multipart",
    "https-url"
  ],
  "maxFileBytes": 10485760,
  "maxInputPixels": 20000000,
  "processingMaxEdge": 4096,
  "processingMaxPixels": 3145728,
  "maxConcurrency": 2,
  "maxPendingTasks": 6,
  "maxGlobalPendingTasks": 18,
  "resultRetentionSeconds": 86400
}

Response fields

Task task and billing status

Account Quota and Limitations

Error and response headers

{
  "error": {
    "code": "API_CREDIT_INSUFFICIENT"
  },
  "requestId": "f7d692da-01bf-48c8-bb45-28d063b3d9d0"
}

Application errors often include requestIdfor easy troubleshooting; gateway failure may only return error.code, clients should tolerate non-JSON error responses.

Task status and cancellation

Application for cancellation is not confirmation of cancellation

POST /tasks/{taskId}/cancel No request body required. Return If you continue to query when cancel_requested , the quota may still be reserved; it will only be released after the cancellation is confirmed. Returned when the conversion has completed first succeeded, settled according to the successful result.

Idempotent keys cover the entire logical task

The same idempotent key and image for the same account will return the original taskId, including if the task has succeeded, failed, or expired; it will not "rerun" the original task. If the original image is different, 409 will be returned. In case of HTTP timeout or status confirmation, the query will be resumed first; a new key will be created only when the original task final status is confirmed and there is a new business intention.

The current task record and idempotent information will not be cleared when the result file is deleted. Don't recycle historical idempotent keys after the task ends.

Billing and quota reservation

The number of historical successes is accumulated permanently by API account and is shared by all keys. Segmented pricing does not allow retroactive price changes. The total of 1,500 payments through balance is 275 yuan. Recharging only increases the balance but does not increase the number of successful calls.

• Reserve the current balance unit price when receiving the task. If the account already has a valid call quota issued by management, the quota will be deducted first; the call count package is currently not sold.
• The result is settled once after being successfully archived. Failure, confirmation of cancellation or queue expiration will release the reservation, and the number of successes will not be increased.
• Only the number of packages or the balance can be deducted for the same task. When the status is unknown, the reservation will be kept and the confirmation will be restored without immediate recharge or refund.
• If two balance tasks are concurrently executed after the 999th time, 20 points can be reserved for each; the successful serial numbers are 1000 and 1001 respectively, and 20 points and 15 points are actually deducted, and the extra 5 points reserved are released.
• There is no charge for querying status, capacity, quota, usage and repeated downloads; the number of HTTP requests is not equal to the number of billed calls.

The API console provides four levels of balance recharge: ¥10, ¥50, ¥100, and ¥500. The payment amount is credited to the account at a ratio of 1:1. No call packages are sold. Whether WeChat payment is open depends on the actual environment; local preview is closed for real payment. Automatic refunds have not yet been implemented, and the test amount does not represent the actual recharge.

Current limiting, timeout and retry

429 Priority Compliance Retry-After; Network error, 500/502/503/504 Use capped backoff to add jitter to production. Do not automatically retry 400, 401, 402, 403, 404, 410, 413, fix the cause first. 409 Only IMAGE_FETCH_IN_PROGRESS can preserve original input, original idempotent key limited backoff; IDEMPOTENCY_CONFLICT must be stopped.

Submission response loss may occur after the server has received it. Retransmission must retain the original key and original file; if the download fails, only the original download path will be retried. Stopping polling locally will not stop the server task. Only by canceling the interface can you apply for cancellation.

Error code and troubleshooting

Determine the HTTP status first, and then error.code. Query task returns HTTP 200 but When status=failed , the business conversion still fails, you should check the task errorCode。

Task failure may be related to input exceptions, conversion failures, or queue expiration. There will be no deduction for failed tasks, and the original idempotent key will still return to the original final state. Please check the cause of the error and do not automatically change keys and submit again. encounter When STATE_RECONCILING is entered, the taskId is retained and the query is continued without retransmitting the key. When contacting the service provider, provide taskId, requestId and error code, but do not provide the complete Key or private image.

OpenAPI and Debugging Tools

Provides OpenAPI 3.0.3 JSON for use with Postman, Apifox, or OpenAPI-enabled client generation tools. The specification only includes the 7 external v1 interfaces and does not include console sessions, management interfaces, or internal information.

1. Import the downloaded JSON and configure the service address as https://svgo-api.com/openapi/v1。
2. Set the Bearer Key in a local private environment variable and do not synchronize the real Key to the public workspace or shared collection.
3. Submit interface optional form-data image file field, or raw JSON imageUrl; supplement the independent Idempotency-Key request header.
4. Check capabilities first, then submit; save taskId, and download in file response mode after success.

Interface changes are managed through version management. There is currently no official npm/PyPI SDK released; the download examples in the documentation can be used directly, but asynchronous polling and idempotent recovery logic still need to be retained after generating the client.