v1

latestOpenAPI 3.0.32026-07-241112213.6 KB

Submit Task

Submit an asynchronous Storyboard image generation task. Returns a taskId for polling results via the 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

post/v1/common_task/storyboard/task/submit

Headers

Topview-Uidstring required

User ID

Authorizationstring required

API key for authentication. Format: Bearer {apiKey}

Request body

storystring 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

resolutionstring 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

gridSizestring

Storyboard/grid panel count (optional). preset mode: 4 / 9 / 25; custom mode: 2~25. Default 9

targetDurationSecondsinteger

Target total video duration in seconds, used to assist storyboard planning. Default 15

referenceFileIdsstring[]

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)

boardIdstring

Associated Board ID (optional). When provided, a corresponding boardTask is created in aigc-backend; the response may include boardId

noticeUrlstring

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

Example request

{
  "story": "An astronaut on Mars discovers a mysterious signal and follows it to an ancient alien ruin...",
  "model": "Nano Banana 2",
  "aspectRatio": "16:9",
  "resolution": "1K",
  "gridMode": "preset",
  "gridSize": "9",
  "targetDurationSeconds": 15,
  "referenceFileIds": [
    "file_abc123",
    "file_def456"
  ],
  "boardId": "board_xxx",
  "noticeUrl": "https://example.com/topview/callback"
}

Response

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

codestring

Business status code; 200 on success

messagestring

Status message

Example response

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "6f4b5a8c9d0e1f2a3b4c5d6",
    "status": "success"
  }
}