Text-to-Image / Image Edit Task API Usage

Common Conventions

• All interfaces require request headers Authorization: Bearer <apiKey> and Topview-Uid: <userId>
• Successful response unified structure: { "code": "200", "message": "Success", "result": { ... } }
• After task submission, returns taskId. Frontend polls the query interface to get results

I. Text-to-Image

1.1 Submit Task

POST /v1/common_task/text2image/task/submit

Request Headers

Request Body (JSON)

Supported Models and Parameter Constraints

Note: The model parameter should use the model display name (e.g., "Nano Banana 2"), not the code.

• aspectRatio: Required for all models, must be one of the supported ratios for that model
• resolution: Models marked as "required" must pass this parameter; models marked as "not supported, do not pass" will return an error if provided
• quality: Supported only by GPT Image 2 and Reve Image; defaults to medium when omitted; other models return an error if provided
• generateCount: 1~4, required

Request Example

POST /v1/common_task/text2image/task/submit
Topview-Uid: user_123

{
  "model": "GPT Image 2",
  "prompt": "A futuristic city skyline at dusk, neon lights reflected on wet streets, cinematic composition",
  "aspectRatio": "16:9",
  "resolution": "2K",
  "quality": "high",
  "generateCount": 2
}

Response Example

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "task_t2i_20251128001",
    "status": "success",
    "noticeUuid": "uuid_abc"
  }
}

If boardId is provided, the response will additionally return boardTaskIds and boardId fields.

1.2 Query Task Result

GET /v1/common_task/text2image/task/query

Request Parameters (Query)

Request Example

GET /v1/common_task/text2image/task/query?taskId=task_t2i_20251128001
Topview-Uid: user_123

Response Example (In Progress)

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "task_t2i_20251128001",
    "status": "running",
    "errorMsg": null,
    "costCredit": "0.000",
    "images": []
  }
}

Response Example (Success)

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "task_t2i_20251128001",
    "status": "success",
    "errorMsg": null,
    "costCredit": "0.400",
    "images": [
      {
        "status": "success",
        "errorMsg": null,
        "fileId": "file_img_001",
        "filePath": "https://cdn.example.com/images/output_001.jpg",
        "width": 2560,
        "height": 1440,
        "boardTaskId": null
      },
      {
        "status": "success",
        "errorMsg": null,
        "fileId": "file_img_002",
        "filePath": "https://cdn.example.com/images/output_002.jpg",
        "width": 2560,
        "height": 1440,
        "boardTaskId": null
      }
    ]
  }
}

Response Example (Failure)

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "task_t2i_20251128001",
    "status": "fail",
    "errorMsg": "Model service unavailable",
    "costCredit": "0.000",
    "images": []
  }
}

II. Image Edit

Image editing supports generating edited images by providing one or more reference images + a prompt. Supports instruction-based modifications, style transfer, and other scenarios.

2.1 Submit Task

POST /v1/common_task/image_edit/task/submit

Request Headers

Request Body (JSON)

Supported Models and Parameter Constraints

Note: The model parameter should use the model display name (e.g., "Seedream 5.0"), not the code.

Request Example

POST /v1/common_task/image_edit/task/submit
Topview-Uid: user_123

{
  "model": "GPT Image 2",
  "prompt": "Change the background to a snowy mountain landscape, keep the subject unchanged",
  "inputImageFileIds": ["file_src_img_001"],
  "aspectRatio": "1:1",
  "resolution": "2K",
  "quality": "medium",
  "generateCount": 1
}

Request Example (Multi-Image Reference)

POST /v1/common_task/image_edit/task/submit
Topview-Uid: user_123

{
  "model": "Nano Banana 2",
  "prompt": "Blend the style of both images into a unified artistic composition",
  "inputImageFileIds": ["file_img_style001", "file_img_content001"],
  "aspectRatio": "1:1",
  "resolution": "2K",
  "generateCount": 2
}

Response Example

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "task_ie_20251228001",
    "status": "success",
    "noticeUuid": "uuid_ie_xyz"
  }
}

If boardId is provided, the response will additionally return boardTaskIds and boardId fields.

2.2 Query Task Result

GET /v1/common_task/image_edit/task/query

Request Parameters (Query)

Request Example

GET /v1/common_task/image_edit/task/query?taskId=task_ie_20251228001
Topview-Uid: user_123

Response Example (Success)

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "task_ie_20251228001",
    "status": "success",
    "errorMsg": null,
    "costCredit": "0.200",
    "images": [
      {
        "status": "success",
        "errorMsg": null,
        "fileId": "file_edited_001",
        "filePath": "https://cdn.example.com/images/edited_001.jpg",
        "width": 2560,
        "height": 1440,
        "boardTaskId": null
      }
    ]
  }
}

Response Example (Partial Success)

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "task_ie_20251228002",
    "status": "success",
    "errorMsg": "Partial tasks failed (1/2): Content policy violation",
    "costCredit": "0.200",
    "images": [
      {
        "status": "success",
        "errorMsg": null,
        "fileId": "file_edited_002",
        "filePath": "https://cdn.example.com/images/edited_002.jpg",
        "width": 2560,
        "height": 1440,
        "boardTaskId": null
      },
      {
        "status": "fail",
        "errorMsg": "Content policy violation",
        "fileId": null,
        "filePath": null,
        "width": null,
        "height": null,
        "boardTaskId": null
      }
    ]
  }
}

III. Common Specifications

Task Status Enumeration

Polling Recommendations

Recommended polling interval: 3–5 seconds, timeout should be set to 5 minutes.

Sub-tasks in images

When generateCount > 1, the images list contains multiple sub-task results. Each sub-task has an independent status.

• Parent task status=success: All sub-tasks are completed (some sub-tasks may be fail, check the sub-task's status and errorMsg)
• Parent task status=fail: All sub-tasks failed

When partial failures occur, the parent task's errorMsg summarizes the failure reasons, e.g., "Partial tasks failed (1/2): Content policy violation".

Query Response Fields

IV. Credit Billing Explanation

totalCost = unitCost × generateCount

Credit types: Text-to-Image is common_task_text2image, Image Edit is common_task_image_edit.

Billing Explanation: Credits are deducted when the task is submitted, settled based on actual consumption when the task succeeds, and refunded if the task fails.

Pricing Rules:

• Models that support quality: prefer pricing[resolution_quality] (e.g., pricing["2K_high"]); when omitted, API defaults to medium
• Models with resolution but without quality: price by pricing[resolution] (e.g., pricing["2K"])
• Models without resolution parameter: price by pricing["default"]

4.1 Text-to-Image (textToImage) Pricing Table

Models Billed by Resolution (Unit: Credits/Generation, generateCount=1)

Fixed Price Models (Unit: Credits/Generation, not differentiated by resolution)

4.2 Image Edit (imageEdit) Pricing Table

Image Edit pricing follows Text-to-Image model pricing in general. Image Edit does not include Imagen 4, GPT Image 1.5, or Reve Image; Reve Image Edit / Reve Image Remix support Image Edit only; Wan 2.7 Image Pro in Image Edit supports only 1K/2K (no 4K pricing).

Models Billed by Resolution (Unit: Credits/Generation, generateCount=1)

Fixed Price Models (Unit: Credits/Generation, not differentiated by resolution)