API Reference

Prerequisites

Before starting with the ImgMCP API, please ensure you have the following ready:

1. An ImgMCP Account: You need to register on the platform. If you don't have an account yet, please go to the Dashboard to complete the registration.
2. An API Key: An API key is required to authenticate your requests. After registering and logging in, you can find your default API key on the API Keys page in the Management Console.

Please keep your API key secure and confidential.

Core Configuration

• API Base URL:

https://api.imgmcp.com

• Authentication Method: ImgMCP uses API keys for authentication. You need to provide the key in the Authorization header of your HTTP request in the following format:

Authorization: Bearer <Your API Key>

API Endpoints

Imagine

POST /v1/imagine

Create new multimedia generation tasks including images, audio, video, and other content types.

Request Parameters:

Note: Different models may accept additional parameters specific to their functionality and may have varying requirements for the above parameters.

Request Example:

curl -X POST https://api.imgmcp.com/v1/imagine \
-H "Authorization: Bearer <Your API Key>" \
-H "Content-Type: application/json" \
-d '{
    "n": 2,
    "model": "gpt-image-1",
    "style": "",
    "prompt": "A beautiful sunset over mountain peaks",
    "reference": ["https://example.com/ref1.jpg", "https://example.com/ref2.jpg"]
}'

Response Example:

{
    "ids": ["task-uuid-1", "task-uuid-2"]
}

Reimagine

POST /v1/reimagine

Perform actions on existing multimedia generation results to create new variations or enhancements.

Request Parameters:

Action Types:

• upscale: Enhance the resolution or quality of the selected multimedia content
• variation: Generate variations of the selected multimedia content
• reroll: Regenerate the entire task with new results

Request Example:

curl -X POST https://api.imgmcp.com/v1/reimagine \
-H "Authorization: Bearer <Your API Key>" \
-H "Content-Type: application/json" \
-d '{
    "task_id": "task-uuid-2",
    "index": 1,
    "action": "upscale"
}'

Response Example:

{
    "ids": ["task-uuid-3"]
}

Task Query

GET /v1/tasks

Retrieve a paginated list of user tasks with optional filtering.

Query Parameters:

Task Status Values:

• 0: Pending
• 1: Processing
• 2: Completed
• 3: Failed

Request Example:

curl -X GET "https://api.imgmcp.com/v1/tasks?page=1&pageSize=10" \
-H "Authorization: Bearer <Your API Key>"

Response Example:

{
  "total": 1,
  "page": 1,
  "pageSize": 100,
  "tasks": [
    {
      "id": "task-uuid-1",
      "model": "gpt-image-1",
      "style": "",
      "cost": 10,
      "request": {
        "n": 1,
        "model": "gpt-image-1",
        "prompt": "A beautiful sunset over mountain peaks",
        "reference": [
          "https://example.com/ref1.jpg",
          "https://example.com/ref2.jpg"
        ]
      },
      "response": {
        "assets": [
          "asset-uuid-1",
          "asset-uuid-2",
          "asset-uuid-3",
          "asset-uuid-4"
        ]
      },
      "status": 2,
      "startedAt": "2025-06-11T15:18:42Z",
      "finishedAt": "2025-06-11T15:20:37Z",
      "createdAt": "2025-06-11T15:18:42Z",
      "updatedAt": "2025-06-11T15:20:37Z"
    }
  ]
}

Error Handling

All endpoints return consistent error responses:

{
    "message": "Error message describing what went wrong"
}

Common HTTP Status Codes:

• 400: Bad Request - Invalid parameters
• 401: Unauthorized - Invalid or missing API key
• 403: Forbidden - Insufficient permissions
• 429: Too Many Requests - Rate limit exceeded
• 500: Internal Server Error - Server-side error

Next Steps:

You have successfully configured ImgMCP API access. You can now start exploring the various image generation and management capabilities provided by the platform. Refer to subsequent sections for more detailed usage examples.