How APIMart Task ID Validation Works in the awesome-gpt-image-2 Integration

The APIMart integration validates task IDs using a centralized isValidApimartTaskId function that enforces a strict regex pattern requiring the prefix task_ followed by 8–180 alphanumeric characters, hyphens, or underscores.

The freestylefly/awesome-gpt-image-2 repository implements a robust validation layer for APIMart task identifiers to prevent malformed requests and ensure consistent error handling across client and server environments. By centralizing the validation logic in a shared utility, the codebase maintains uniform security standards whether polling generation status from the browser or handling API requests server-side.

The Core Validation Function

All APIMart task ID validation flows through a single source of truth defined in the shared utilities layer.

Regex Pattern and Constraints

The validation logic resides in shared/apimart.js, where the isValidApimartTaskId function applies a precise regular expression to verify identifier formatting:

// https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js#L27-L28
export function isValidApimartTaskId(taskId) {
  return /^task_[a-zA-Z0-9_-]{8,180}$/.test(String(taskId || ''));
}

The regex enforces three specific constraints:

• Literal prefix: Must begin with task_
• Length requirement: Exactly 8 to 180 characters following the prefix
• Character set: Only letters (a-z, A-Z), numbers (0-9), underscores (_), and hyphens (-) are permitted

This strict whitelisting approach prevents injection attacks and ensures compatibility with APIMart's internal identifier scheme.

Where Validation Occurs in the Codebase

The validator is invoked at every entry point where a task ID enters the system, creating a defensive perimeter around network operations.

Client-Side Validation in apimartClient.js

Both public polling methods in src/apimartClient.js validate identifiers before transmitting requests. The fetchPersonalTask function (line 125) checks the task ID and throws a specific error code if validation fails:

// https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js#L125-L130
export async function fetchPersonalTask(taskId, apiKey, language, fetchImpl = fetch) {
  if (!isValidApimartTaskId(taskId)) {
    const error = new Error('APIMART_INVALID_TASK');
    error.code = error.message;
    throw error;
  }
  // ... network request logic
}

Similarly, fetchPlatformTask (line 73) implements identical guards for platform-level generation polling:

// https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js#L73-L77
export async function fetchPlatformTask(taskId, accessToken, language, fetchImpl = fetch) {
  if (!isValidApimartTaskId(taskId)) {
    const error = new Error('APIMART_INVALID_TASK');
    error.code = error.message;
    throw error;
  }
  // ... network request logic
}

Server-Side Validation in API Routes

The server-side endpoint in api/generation/status.js validates incoming query parameters before processing status lookups. Line 39 trims the input and applies the same validator used on the client:

// https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generation/status.js#L39-L41
const taskId = String(req.query?.taskId || '').trim();
if (!isValidApimartTaskId(taskId)) {
  // respond with error...
}

This dual validation ensures that malicious or malformed IDs are rejected before consuming database resources or external API quotas.

Why Centralized Validation Matters

Consolidating APIMart task ID validation into shared/apimart.js provides three architectural advantages:

• Security: Malformed strings are rejected at the application boundary, preventing unnecessary network traffic and reducing the attack surface for injection attempts
• Consistency: Client-side and server-side code share identical rules, eliminating discrepancies that could cause silent failures or debugging difficulties
• Maintainability: Changes to the identifier format require updates to only one function, automatically propagating to fetchPersonalTask, fetchPlatformTask, and all API endpoints

Summary

• The isValidApimartTaskId function in shared/apimart.js serves as the single validation authority for the entire APIMart integration
• The regex /^task_[a-zA-Z0-9_-]{8,180}$/ requires identifiers to start with task_ and contain 8–180 allowed characters
• Client-side validation occurs in src/apimartClient.js within fetchPersonalTask (line 125) and fetchPlatformTask (line 73), throwing APIMART_INVALID_TASK errors for malformed IDs
• Server-side validation mirrors the client logic in api/generation/status.js (line 39) to protect backend resources
• Centralizing the validator ensures consistent security policies and simplified maintenance across the freestylefly/awesome-gpt-image-2 codebase

Frequently Asked Questions

What happens if I provide an invalid task ID to the APIMart client?

The function throws an error with the code APIMART_INVALID_TASK before any network request occurs. This immediate failure prevents wasted API calls and allows your application to catch the error and display a user-friendly validation message.

Can I modify the allowed length of APIMart task IDs?

Yes, but you must update the regex in shared/apimart.js. The current implementation limits the suffix to between 8 and 180 characters ({8,180}). Changing these values will affect validation across both client and server code, ensuring consistency throughout the application.

Why does the validation require the task_ prefix?

The prefix acts as a namespace guard that prevents accidental submission of unrelated identifiers (such as database IDs or user-generated strings) to the APIMart service. This explicit formatting requirement ensures that only legitimate APIMart task identifiers are transmitted to the external API.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}