---
title: "Submit Task"
method: POST
path: "/v1/common_task/storyboard/task/submit"
---

# Submit Task

`POST /v1/common_task/storyboard/task/submit`

Submit an asynchronous Storyboard image generation task. Returns a `taskId` for polling results via the [Query Task](https://docs.topview.ai/update/reference/storyboard-query-task) API.The system converts the user's story text (and optional reference images) into a storyboard grid preview image (Stage 1; does not include subsequent video generation).  **Models**: Supports `GPT Image 2`, `Nano Banana 2`, and `Nano Banana Pro` (pass displayName or model code; case-insensitive).  **Parameter rules**:  - `story` is required, max 5000 characters- `aspectRatio` on the public API only supports `16:9`, `9:16`, `1:1`; default `16:9` -  `resolution` is required; allowed values vary by model: GPT Image 2 / Nano Banana Pro → `1K`/`2K`/`4K`; Nano Banana 2 → `512p`/`1K`/`2K`/`4K`- `gridMode` supports `auto` / `preset` / `custom`; default `preset` - When `gridMode=preset`, `gridSize` must be `4` / `9` / `25`; default `9` - When `gridMode=custom`, `gridSize` supports 2~25- `targetDurationSeconds` defaults to 15; must be ≥ 1 - `referenceFileIds` is an optional list of image fileIds; GPT Image 2 max 16, Nano Banana 2 max 14, Nano Banana Pro max 6  **Credits**: Charged after task completion. Use `costCredit` in the query response to check consumption.  **Common error codes**:  -  `4000`: Invalid parameters (empty story, unsupported aspectRatio/resolution, invalid gridSize, etc.)  - `4100`: Insufficient credits - `5000`: Internal server error

## Headers

- `Topview-Uid` string, required
- `Authorization` string, required

## Request body

- object
  - `story` string, required — Story text (required). The system breaks it into storyboard keyframes and generates a grid preview image. Max 5000 characters
  - `model` 'GPT Image 2' | 'Nano Banana 2' | 'Nano Banana Pro', required — Model name (required). Allowed values: `GPT Image 2`, `Nano Banana 2`, `Nano Banana Pro` (case-insensitive; model code also accepted)
  - `aspectRatio` '16:9' | '9:16' | '1:1' — Aspect ratio (optional). Public API only supports `16:9`, `9:16`, `1:1`; default `16:9`
  - `resolution` string, required — Resolution (required). GPT Image 2 / Nano Banana Pro: `1K`/`2K`/`4K`; Nano Banana 2: `512p`/`1K`/`2K`/`4K`
  - `gridMode` 'auto' | 'preset' | 'custom' — Storyboard panel count mode. `auto`: auto-infer; `preset`: use preset grid count; `custom`: custom grid count. Default `preset`
  - `gridSize` string — Storyboard/grid panel count (optional). `preset` mode: `4` / `9` / `25`; `custom` mode: 2~25. Default `9`
  - `targetDurationSeconds` integer — Target total video duration in seconds, used to assist storyboard planning. Default 15
  - `referenceFileIds` string[] — Reference image fileId list (optional). Must be uploaded via the upload API first. Max count varies by model (GPT Image 2: 16, Nano Banana 2: 14, Nano Banana Pro: 6)
  - `boardId` string — Associated Board ID (optional). When provided, a corresponding boardTask is created in aigc-backend; the response may include boardId
  - `noticeUrl` string — Callback URL on task completion (optional). When configured, the response includes noticeUuid and the system sends a notification to this URL when the task finishes

## Response `200`

Accepted successfully (task created and queued; poll the query API for execution result)

- object
  - `code` string — Business status code; 200 on success
  - `message` string — Status message
  - `result` object — Submission result (TaskPair)
    - `taskId` string — Task ID for polling via the query API
    - `status` 'init' | 'running' | 'success' | 'fail' — Immediate acceptance status after submission; always `success` on acceptance. Use the query API for execution status (init/running/success/fail)
    - `errorMsg` string — Error message on submission failure (may be present when acceptance fails)
    - `subTaskId` string — Sub-task ID (returned in some business scenarios; usually not returned by this API)
    - `boardTaskIds` string[] — Board sub-task ID list when associated with a Board
    - `boardId` string — Board ID when associated with a Board
    - `noticeUuid` string — Async callback notification UUID (returned when noticeUrl is configured in the request body)

---

[API](https://skmtc.net/topview/apis/image-character-swap-apis-editable-in-readme.md) · [All operations](https://skmtc.net/topview/apis/image-character-swap-apis-editable-in-readme/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/topview/image-character-swap-apis-editable-in-readme/revisions/83cd46ca7859/schema)