---
title: "Create an image generation task"
method: POST
path: "/api/v1/images"
tags: ["Generation"]
---

# Create an image generation task

`POST /api/v1/images`

## Request

- Base URL: `https://viewmax.studio`
- URL: `https://viewmax.studio/api/v1/images`
- Auth: HTTP bearer

Validates the request, charges credits, and submits the job before responding; most models render asynchronously. Poll GET /api/v1/tasks/{taskId}. On Pro and Ultra, flagship image models can be covered by the daily plan allowance (`costCredits: 0`).

## Headers

- `Idempotency-Key` string

## Request body

- CreateImageRequest
  - `model` string, required: Model id from GET /api/v1/models?type=image.
  - `prompt` string, required
  - `scene` 'text-to-image' | 'image-to-image': Default: `image-to-image` when `image_urls` is non-empty, else `text-to-image`.
  - `image_urls` string[]: Required (at least one) for `image-to-image`. ViewMax sets no count limit; the model provider may.
  - `options` object
    - `aspect_ratio` string
    - `quality` string: One of the scene's `qualities`, e.g. `1K`/`2K`/`4K`, `Basic`/`High`, or `Low`/`Medium`/`High`/`XHigh`/`Max` (GPT Image 2.5).
    - `resolution` '1K' | '2K' | '4K': GPT Image 2.5 (default `1K`). Other models read it as `quality` when `quality` is omitted.
    - `size` string: GPT Image 2.5 exact pixels, e.g. `1536x1024`: multiples of 16, longest side ≤ 3840, ratio ≤ 3:1, 655,360–8,294,400 pixels. Overrides `aspect_ratio` and `resolution`.

## Response `200`

Task created, or the existing task for a repeated `Idempotency-Key`.

- object
  - `code` 0, required
  - `message` 'ok', required
  - `data` Task, required: Generation task. Returned by every create endpoint and by GET /api/v1/tasks/{taskId}.
    - `id` string, required: Task id. Poll GET /api/v1/tasks/{taskId} with it.
    - `status` 'pending' | 'processing' | 'success' | 'failed' | 'canceled', required: `pending`/`processing`: keep polling. `success`: read `taskUrls`. `failed`/`canceled`: terminal, credits refunded.
    - `mediaType` 'video' | 'image' | 'music' | 'audio', required
    - `scene` string: Mode or scene, e.g. `text-to-video`, `text-to-image`, `text-to-music`, `text-to-speech`, `text-to-sound-effects`.
    - `model` string: Model identifier used for the job. May differ from the catalog id sent in the request.
    - `prompt` string
    - `options` string, nullable: JSON-encoded options as priced and submitted, including filled-in defaults and `mode` for video.
    - `taskUrls` string[], required: Result URLs. Empty until the task succeeds.
    - `costCredits` integer, required: Credits charged. `0` when a plan allowance covered it.
    - `waivedCredits` integer: Normal price waived by a plan allowance; otherwise `0`.
    - `fairUseKey` string, nullable: Plan allowance slot used by this task, or `null`.
    - `taskInfo` string, nullable: JSON string. While pending/processing/success it holds job diagnostics whose shape is not stable. On `failed`/`canceled` it is `{"errorCode","error","errorMessage"}`; `errorCode` is one of `insufficient_credits`, `auth_required`, `rate_limited`, `request_cancelled`, `provider_unavailable`, `invalid_input`, `content_rejected`, `busy`, `duplicate_request`, `generic`. `errorMessage` carries the provider's reason only for `invalid_input`.
    - `taskResult` string, nullable: JSON string. Same failure payload as `taskInfo` on `failed`/`canceled`; otherwise job diagnostics with no stable shape.
    - `taskId` string, nullable: Upstream job id (diagnostic only).
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `userId` string
    - `creditId` string, nullable
    - `visibility` string
    - `deletedAt` string, date-time, nullable

## Other responses

- `400`: `invalid_request`: fix the request using `message` before retrying (includes disabled or offline models). `content_rejected`: change the prompt or media. When the provider rejected an accepted task, `error.task_id` is set and the task is failed and refunded.
- `401`: Missing or invalid API key (`code: -1001`).
- `402`: Balance below the task cost (`code: -1002`). No task was created; do not retry until credits are added.
- `500`: Provider or server failure. With `error.task_id` the task failed and was refunded: retry once. When the hint says the outcome is unknown, the task stays `pending` with the charge kept: poll it instead of retrying.
- `503`: External content-safety check temporarily unavailable. Retry after a short delay.

---

[API](https://skmtc.dev/viewmax/apis/viewmax-studio-api.md) · [All operations](https://skmtc.dev/viewmax/apis/viewmax-studio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/viewmax/apis/viewmax-studio-api/revisions/c4f378e09f44?raw)