Images

Create an image caption task

POST/images/captions

Generate a short caption for an input image in the requested language. The request can run synchronously or return a task for polling.

Request Body

Content-Type: application/jsonRequired: true

Request Body Schema

application/json

└input_image

required

string(Input Image)

Source image input to analyze and caption. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└language

required

string(Language)[1..64] chars

Target language for the generated caption, for example English, Chinese, or Japanese.

└options

TaskRequestOptions | null

Optional task execution controls for the task

└block

boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

└priority

integer | null[0..255]

Task dispatch priority within this client. Larger values are consumed earlier. Must not exceed the client's `mq_priority`. When omitted, defaults to the client's `mq_priority`.

Responses

For standard error codes, see Error Handling.

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

string(Result)

Short caption generated for the input image in the requested language.

└metadata

ImageCaptionMetadata | null

Additional caption metadata including description and keywords.

└description

string(Description)

Brief description of the image content.

Default: ``

└keywords

array(Keywords)

Relevant keywords describing the image.

└keywords[]

string

This endpoint may also return 201 when the task is accepted for asynchronous execution. Use the task_uuid from the response body to poll the corresponding GET endpoint for the result. Sync vs async →

Try It

curl https://api.v2fun.ai/api/v1/images/captions \
  -X POST \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "input_image": "<input_image>",
      "language": "<language>"
    }'

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": "<result>"
}

Get an image caption task

GET/images/captions/{task_uuid}

Retrieve the current status or final result of an image caption task.

Parameters

Name	In	Required	Type	Description
task_uuid	path	Yes	string	Task UUID returned when the image caption job was created.

Responses

For standard error codes, see Error Handling.

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

string(Result)

Short caption generated for the input image in the requested language.

└metadata

ImageCaptionMetadata | null

Additional caption metadata including description and keywords.

└description

string(Description)

Brief description of the image content.

Default: ``

└keywords

array(Keywords)

Relevant keywords describing the image.

└keywords[]

string

Try It

curl https://api.v2fun.ai/api/v1/images/captions/<task_uuid> \
  -H "Authorization: Bearer $YOUR_API_KEY"

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": "<result>"
}

Create a prompt enhancement task

POST/images/prompt_enhancements

Improve or expand an image prompt before it is used for image generation. The request can run synchronously or return a task for polling.

Request Body

Content-Type: application/jsonRequired: true

Request Body Schema

application/json

└prompt

required

string(Prompt)

User prompt to rewrite or expand before image generation.

└system_prompt

required

string(System Prompt)

System instruction that guides how the prompt should be enhanced.

└options

TaskRequestOptions | null

Optional task execution controls for the task

└block

boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

└priority

integer | null[0..255]

Task dispatch priority within this client. Larger values are consumed earlier. Must not exceed the client's `mq_priority`. When omitted, defaults to the client's `mq_priority`.

Responses

For standard error codes, see Error Handling.

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

string(Result)

Enhanced prompt returned by the prompt-improvement pipeline.

└metadata

any(Metadata)

Additional task-specific metadata returned with the result.

This endpoint may also return 201 when the task is accepted for asynchronous execution. Use the task_uuid from the response body to poll the corresponding GET endpoint for the result. Sync vs async →

Try It

curl https://api.v2fun.ai/api/v1/images/prompt_enhancements \
  -X POST \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "prompt": "<prompt>",
      "system_prompt": "<system_prompt>"
    }'

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": "<result>"
}

Get a prompt enhancement task

GET/images/prompt_enhancements/{task_uuid}

Retrieve the current status or final result of a prompt enhancement task.

Parameters

Name	In	Required	Type	Description
task_uuid	path	Yes	string	Task UUID returned when the prompt enhancement job was created.

Responses

For standard error codes, see Error Handling.

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

string(Result)

Enhanced prompt returned by the prompt-improvement pipeline.

└metadata

any(Metadata)

Additional task-specific metadata returned with the result.

Try It

curl https://api.v2fun.ai/api/v1/images/prompt_enhancements/<task_uuid> \
  -H "Authorization: Bearer $YOUR_API_KEY"

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": "<result>"
}

Create an image generation task

POST/images/generations

Submit a text-to-image generation request and receive a task reference for polling.

Request Body

Content-Type: application/jsonRequired: true

Request Body Schema

application/json

└model

string(Model)

Image generation model to run for this request. Available values: `qwen-image`, `nano-banana-pro`, `nano-banana-2`, `nano-banana-2-lite`, `gpt-image-2`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-flare`.

Default: `qwen-image`

└prompt

required

string(Prompt)

Natural-language prompt describing the image to generate.

└size

string(ImageSizeEnum)

Enum: 1024x1024 1152x864 864x1152 1280x720 720x1280

└background

string(BackgroundEnum)

Enum: opaque transparent

└options

TaskRequestOptions | null

Optional task execution controls for the task

└block

boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

└priority

integer | null[0..255]

Task dispatch priority within this client. Larger values are consumed earlier. Must not exceed the client's `mq_priority`. When omitted, defaults to the client's `mq_priority`.

Responses

For standard error codes, see Error Handling.

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

Generated, edited, or processed image URI list. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

any(Metadata)

Additional task-specific metadata returned with the result.

This endpoint may also return 201 when the task is accepted for asynchronous execution. Use the task_uuid from the response body to poll the corresponding GET endpoint for the result. Sync vs async →

Try It

curl https://api.v2fun.ai/api/v1/images/generations \
  -X POST \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "prompt": "<prompt>"
    }'

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

Get an image generation task

GET/images/generations/{task_uuid}

Retrieve the current status or final output of an image generation task.

Parameters

Name	In	Required	Type	Description
task_uuid	path	Yes	string	Task UUID returned when the image generation job was created.

Responses

For standard error codes, see Error Handling.

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

Generated, edited, or processed image URI list. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

any(Metadata)

Additional task-specific metadata returned with the result.

Try It

curl https://api.v2fun.ai/api/v1/images/generations/<task_uuid> \
  -H "Authorization: Bearer $YOUR_API_KEY"

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

Create an image edit task

POST/images/edits

Submit an image editing request based on one or more source images and an optional prompt.

Request Body

Content-Type: application/jsonRequired: true

Request Body Schema

application/json

└model

string(Model)

Image editing model to run for this request. Available values: `qwen-image-edit`, `nano-banana-pro`, `nano-banana-2`, `nano-banana-2-lite`, `gpt-image-2`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-flare`, `gpt-multiview`.

Default: `qwen-image-edit`

└prompt

string | null

Optional prompt describing the requested edit or transformation.

└input_images

string[] | null[1..3] items

One to three source images used as editing inputs. Each item may be an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└input_images[]

string

└size

string(ImageSizeEnum)

Enum: 1024x1024 1152x864 864x1152 1280x720 720x1280

└background

string(BackgroundEnum)

Enum: opaque transparent

└options

TaskRequestOptions | null

Optional task execution controls for the task

└block

boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

└priority

integer | null[0..255]

Task dispatch priority within this client. Larger values are consumed earlier. Must not exceed the client's `mq_priority`. When omitted, defaults to the client's `mq_priority`.

Responses

For standard error codes, see Error Handling.

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

Generated, edited, or processed image URI list. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

any(Metadata)

Additional task-specific metadata returned with the result.

This endpoint may also return 201 when the task is accepted for asynchronous execution. Use the task_uuid from the response body to poll the corresponding GET endpoint for the result. Sync vs async →

Try It

curl https://api.v2fun.ai/api/v1/images/edits \
  -X POST \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

Get an image edit task

GET/images/edits/{task_uuid}

Retrieve the current status or final output of an image editing task.

Parameters

Name	In	Required	Type	Description
task_uuid	path	Yes	string	Task UUID returned when the image edit job was created.

Responses

For standard error codes, see Error Handling.

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

Generated, edited, or processed image URI list. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

any(Metadata)

Additional task-specific metadata returned with the result.

Try It

curl https://api.v2fun.ai/api/v1/images/edits/<task_uuid> \
  -H "Authorization: Bearer $YOUR_API_KEY"

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

Create an image processing task

POST/images/processes

Use SeedVR2 to restore the input image and enhance fine details.

Request Body

Content-Type: application/jsonRequired: true

Request Body Schema

application/json

└model

required

string(Model)

Enum: seedvr2

Image processing operator to apply to the input image. Available values: `seedvr2`.

└input_image

required

string(Input Image)

Source image input to process. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└options

TaskRequestOptions | null

Optional task execution controls for the task

└block

boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

└priority

integer | null[0..255]

Task dispatch priority within this client. Larger values are consumed earlier. Must not exceed the client's `mq_priority`. When omitted, defaults to the client's `mq_priority`.

Responses

For standard error codes, see Error Handling.

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

Generated, edited, or processed image URI list. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

any(Metadata)

Additional task-specific metadata returned with the result.

This endpoint may also return 201 when the task is accepted for asynchronous execution. Use the task_uuid from the response body to poll the corresponding GET endpoint for the result. Sync vs async →

Try It

curl https://api.v2fun.ai/api/v1/images/processes \
  -X POST \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "model": "seedvr2",
      "input_image": "<input_image>"
    }'

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

Get an image processing task

GET/images/processes/{task_uuid}

Retrieve the current status or final output of an image processing task.

Parameters

Name	In	Required	Type	Description
task_uuid	path	Yes	string	Task UUID returned when the image processing job was created.

Responses

For standard error codes, see Error Handling.

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

Generated, edited, or processed image URI list. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

any(Metadata)

Additional task-specific metadata returned with the result.

Try It

curl https://api.v2fun.ai/api/v1/images/processes/<task_uuid> \
  -H "Authorization: Bearer $YOUR_API_KEY"

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}