# Run an AI Image Generator task.

AI tasks are asynchronous. Prefer webhook-based completion handling when the feature supports webhooks. Configure your webhook endpoint, verify webhook signatures, and use the received `task_id` to query the task result after a `success` or `error` notification. See the [webhook integration guide](/develop/webhook.md) for setup and verification details.
If webhooks are not supported or cannot be used in your integration, implement polling. After submitting an AI task, poll the status endpoint at regular intervals (e.g., every 10 seconds) until the task status is `success` or `error`.

Endpoint: POST /s2s/v2.0/task/text-to-image
Security: BearerAuthenticationV2

## Request fields (application/json):

  - `prompt` (string, required)
    Prompt to generate image
    Example: A little cat

  - `negative_prompt` (string)
    Prompt what DO NOT want
    Example: dog

  - `template_id` (string, required)
    ID of the template. List predefined templates first, and use the id of a template.
    Example: good_template_001

  - `steps` (integer)
    Steps affect image quality and time of processing.  Recommended Step Counts  10-15 Steps: Ideal for quick prompt testing and making broad tweaks.  15–20 Steps: The community sweet spot. Most models hit their ideal quality-to-time ratio in this range.  20–30 Steps: Best for generating highly detailed subjects, like faces, fur, or architectural elements.
    Example: 10

  - `cfg_scale` (number)
    The CFG (Classifier-Free Guidance) scale is a mathematical setting that dictates how strictly an AI model adheres to your text prompt.  Low CFG (1 – 4): The AI has high creative freedom. It loosely interprets your prompt, which can lead to abstract, painterly results, or images that wander off-topic entirely.  Medium CFG (5 – 10): The ideal sweet spot. The generator follows your text closely while still maintaining natural, high-quality visuals.  High CFG (11+): The AI clings to every single word in your prompt. While details become sharper and more literal, pushing the scale too high often results in over-saturated colors, noise, and unnatural artifacts.
    Example: 4

  - `seed` (array)
    Each image is generated with a unique seed. Using same seed to recreate the same image. Only accept 1 seed.

  - `width_ratio` (integer)
    The width of ratio of image.
    Example: 3

  - `height_ratio` (integer)
    The height of ratio of image.
    Example: 4

## Response 200 fields (application/json):

  - `status` (integer)
    Response status
    Example: 200

  - `data` (object)

  - `data.task_id` (string)
    ID of this task. Task result is valid to query by this ID for 24 hours.
    Example: grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe

## Response 400 fields (application/json):

  - `status` (integer)
    Response status
    Example: 400

  - `error` (string)
    Error message
    Example: The operation could not be completed

  - `error_code` (string)
    Error code:
* InvalidParameters - Invalid request parameters
* CreditInsufficiency - Insufficient unit to run
* BadRequest - Unexpected request parameter
* InvalidStyleGroup - Invalid style group id
* InvalidStyle - Invalid style id
    Enum: "InvalidParameters", "CreditInsufficiency", "InvalidStyleGroup", "InvalidStyle", "BadRequest"

## Response 401 fields (application/json):

  - `status` (integer)
    Response status
    Example: 401

  - `error` (string)
    Example: Invalid API key

## Response 429 fields (application/json):

  - `status` (integer)
    Response status
    Example: 429

  - `error` (string)
    Example: Too many requests