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

Parameter	Type	Required	Description
`Topview-Uid`	string	Yes	User ID

Request Body (JSON)

Parameter	Type	Required	Description
`model`	string	Yes	Model display name, e.g., `"Nano Banana 2"`, `"Seedream 5.0"`, see supported models table below
`prompt`	string	Yes	Positive prompt text
`aspectRatio`	string	Yes	Aspect ratio, supported values vary by model, see supported models table below
`resolution`	string	Model-dependent	Resolution, e.g., `"512p"`, `"1K"`, `"2K"`, `"4K"`; required for some models, not supported by others, see supported models table below
`generateCount`	integer	Yes	Number of images to generate, `1~4`
`boardId`	string	No	Board ID. When provided, a task record will be created in the Board

Supported Models and Parameter Constraints

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

Model Name	Aspect Ratio Options (aspectRatio)	Resolution (resolution)	Remarks
Nano Banana 2	9:16, 3:4, 1:1, 4:3, 16:9, 2:3, 3:2, 5:4, 4:5, 21:9, 4:1, 1:4, 8:1, 1:8	512p, 1K, 2K, 4K (required)	Supports 14 aspect ratios
Nano Banana Pro	9:16, 3:4, 1:1, 4:3, 16:9	1K, 2K, 4K (required)
Nano Banana	9:16, 3:4, 1:1, 4:3, 16:9	Not supported, do not pass
Seedream 5.0	auto, 9:16, 3:4, 1:1, 4:3, 16:9, 21:9	2K (required, only supports 2K)	`auto` means the model automatically determines the aspect ratio
Seedream 4.5	auto, 9:16, 3:4, 1:1, 4:3, 16:9, 21:9	2K, 4K (required)	`auto` means the model automatically determines the aspect ratio
Seedream 4.0	auto, 9:16, 3:4, 1:1, 4:3, 16:9, 21:9	1K, 2K, 4K (required)	`auto` means the model automatically determines the aspect ratio
Grok Image Pro	1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 2:1, 1:2, 20:9, 9:20, 19.5:9, 9:19.5	1K, 2K (required)	Supports 13 aspect ratios
Grok Image	1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 2:1, 1:2, 20:9, 9:20, 19.5:9, 9:19.5	1K, 2K (required)	Supports 13 aspect ratios
GPT Image 1.5	3:2, 1:1, 2:3	Not supported, do not pass
Kontext-Pro	9:16, 3:4, 1:1, 4:3, 16:9	Not supported, do not pass
Imagen 4	9:16, 3:4, 1:1, 4:3, 16:9	Not supported, do not pass

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
generateCount: 1~4, required

Request Example

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

{
  "model": "Seedream 5.0",
  "prompt": "A futuristic city skyline at dusk, neon lights reflected on wet streets, cinematic composition",
  "aspectRatio": "16:9",
  "resolution": "2K",
  "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)

Parameter	Type	Required	Default	Description
`taskId`	string	Yes	-	Task ID returned from submission
`needCloudFrontUrl`	boolean	No	false	Whether to return CloudFront URL

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

Parameter	Type	Required	Description
`Topview-Uid`	string	Yes	User ID

Request Body (JSON)

Parameter	Type	Required	Description
`model`	string	Yes	Model display name, e.g., `"Seedream 5.0"`, `"Kontext-Pro"`, see supported models table below
`prompt`	string	Yes	Edit prompt text describing the modifications to be made to the image
`inputImageFileIds`	string[]	Yes	List of reference image fileIds, maximum quantity varies by model (get fileId from upload interface)
`aspectRatio`	string	Yes	Aspect ratio; Seedream / Nano Banana / Kontext-Pro series support `"auto"` (follow input image ratio), see supported models table below
`resolution`	string	Model-dependent	Resolution, e.g., `"512p"`, `"1K"`, `"2K"`, `"4K"`; required for some models, not supported by others, see supported models table below
`generateCount`	integer	Yes	Number of images to generate, `1~4`
`boardId`	string	No	Board ID. When provided, a task record will be created in the Board

Supported Models and Parameter Constraints

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

Model Name	Aspect Ratio Options (aspectRatio)	Resolution (resolution)	Max Input Images	Remarks
Nano Banana 2	auto, 9:16, 3:4, 1:1, 4:3, 16:9, 2:3, 3:2, 5:4, 4:5, 21:9, 4:1, 1:4, 8:1, 1:8	512p, 1K, 2K, 4K (required)	14	`auto` follows input image ratio
Nano Banana Pro	auto, 9:16, 3:4, 1:1, 4:3, 16:9	1K, 2K, 4K (required)	6	`auto` follows input image ratio
Nano Banana	auto, 9:16, 3:4, 1:1, 4:3, 16:9	Not supported, do not pass	6	`auto` follows input image ratio
Seedream 5.0	auto, 9:16, 3:4, 1:1, 4:3, 16:9, 21:9	2K (required, only supports 2K)	14	`auto` follows input image ratio
Seedream 4.5	auto, 9:16, 3:4, 1:1, 4:3, 16:9, 21:9	2K, 4K (required)	14	`auto` follows input image ratio
Seedream 4.0	auto, 9:16, 3:4, 1:1, 4:3, 16:9, 21:9	1K, 2K, 4K (required)	5	`auto` follows input image ratio
Grok Image Pro	1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 2:1, 1:2, 20:9, 9:20, 19.5:9, 9:19.5	1K, 2K (required)	1	Single image mode
Grok Image	1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 2:1, 1:2, 20:9, 9:20, 19.5:9, 9:19.5	1K, 2K (required)	1	Single image mode
GPT Image 1.5	3:2, 1:1, 2:3	Not supported, do not pass	8
Kontext-Pro	auto, 9:16, 3:4, 1:1, 4:3, 16:9	Not supported, do not pass	1	Specialized for image editing; single image mode

Request Example

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

{
  "model": "Seedream 5.0",
  "prompt": "Change the background to a snowy mountain landscape, keep the subject unchanged",
  "inputImageFileIds": ["file_src_img_001"],
  "aspectRatio": "auto",
  "resolution": "2K",
  "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)

Parameter	Type	Required	Default	Description
`taskId`	string	Yes	-	Task ID returned from submission
`needCloudFrontUrl`	boolean	No	false	Whether to return CloudFront URL

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

Status Value	Meaning
`init`	Task submitted, waiting for processing
`running`	Task is being processed
`success`	Task completed successfully
`fail`	Task failed, see `errorMsg` field for error reason

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

Field	Type	Description
`taskId`	string	Task ID
`status`	string	Task status, see enumeration above
`errorMsg`	string	Error message (has value when task fails or partially fails)
`costCredit`	number	Credits consumed by task (floating point number)
`boardId`	string	Associated Board ID (returned if task comes from Board)
`images`	array	List of generated image results, each item contains: `status`, `errorMsg`, `fileId`, `filePath`, `width`, `height`, `boardTaskId`

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 with resolution parameter: 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)

Model Name	512p	1K	2K	4K
Nano Banana 2	0.25	0.40	0.60	0.85
Nano Banana Pro	—	0.80	0.80	1.40
Seedream 5.0	—	—	0.20	—
Seedream 4.5	—	—	0.20	0.20
Seedream 4.0	—	0.15	0.15	0.15
Grok Image Pro	—	0.45	0.45	—
Grok Image	—	0.15	0.15	—

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

Model Name	Unit Price
Nano Banana	0.30
GPT Image 1.5	2.00
Kontext-Pro	0.50
Imagen 4	0.50

4.2 Image Edit (imageEdit) Pricing Table

Image Edit pricing is exactly the same as Text-to-Image, but Image Edit does not include Imagen 4 model.

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

Model Name	512p	1K	2K	4K
Nano Banana 2	0.25	0.40	0.60	0.85
Nano Banana Pro	—	0.80	0.80	1.40
Seedream 5.0	—	—	0.20	—
Seedream 4.5	—	—	0.20	0.20
Seedream 4.0	—	0.15	0.15	0.15
Grok Image Pro	—	0.45	0.45	—
Grok Image	—	0.15	0.15	—

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

Model Name	Unit Price
Nano Banana	0.30
GPT Image 1.5	2.00
Kontext-Pro	0.50