Submit a Task

POST /v1/tasks

Item	Value
Content-Type	`application/json`
Success status	`202 Accepted`
Authentication	`Authorization: Bearer YOUR_TASK_API_KEY`
Idempotency	Optional `Idempotency-Key` header

Request Body

Field	Type	Required	Description
`model`	string	Yes	Model name. Must match `params.model` if that field is present.
`modality`	string	No	`image`, `video`, or `3d`. Explicit is recommended; omission works only when the model's modality can be inferred unambiguously.
`params`	object	Yes	Public task parameters for the selected modality. See below and the model list.
`metadata`	object	No	Caller-defined key/value pairs, such as an order ID or trace ID.

If the same Task API key submits the same Idempotency-Key again, LLMAPI returns the existing task even when the new request body differs. Use a unique key for every logical task. Always provide this header for higher-cost video and 3D tasks.

Only public models returned by GET /v1/tasks/models and their configured catalog aliases can be submitted. Every modality requires a matching adapter, an enabled channel-model mapping, and a plan route. No 3D adapter is registered yet, so 3D is not currently executable.

Image Generation

bash

curl https://api.llmapi.site/v1/tasks \
  -H 'Authorization: Bearer YOUR_TASK_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-20260622-001' \
  -d '{
    "model": "gpt-image-2",
    "modality": "image",
    "params": {
      "model": "gpt-image-2",
      "prompt": "a clean studio product photo of a matte black water bottle",
      "n": 2,
      "image_size": "2K",
      "aspect_ratio": "1:1"
    },
    "metadata": { "order_id": "order-20260622-001" }
  }'

Edit with Reference Image

Put reference images in params.images[].image_url. Data URLs are accepted.

json

{
  "model": "gpt-image-2",
  "modality": "image",
  "params": {
    "model": "gpt-image-2",
    "prompt": "Replace the background with a premium studio scene.",
    "images": [{ "image_url": "data:image/png;base64,BASE64_IMAGE" }],
    "n": 1,
    "image_size": "2K",
    "aspect_ratio": "1:1",
    "extra_body": {
      "input_fidelity": "high"
    }
  }
}

Size Parameters

Use image_size and aspect_ratio for portable image sizing. LLMAPI converts them to the selected upstream format, so callers usually do not need to know each provider's protocol details.

Field	Example	Description
`image_size`	`0.5K`, `1K`, `2K`, `3K`, `4K`	Size tier used for routing and billing. Use the model list response for the exact available tiers.
`aspect_ratio`	`1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `4:5`, `5:4`, `21:9`	Desired output ratio. Use the model list response for the exact available ratios.

See Model Specs for common model and protocol size mappings.

Unsupported image params fields, including size, resolution, generationConfig, and contents, return 400. Use the OpenAI Images compatible endpoints if you need to submit OpenAI Images requests with size directly.

Advanced Extension Parameters

Use params.extra_body for upstream-specific options. LLMAPI first derives the selected upstream request from the portable fields, then shallow-merges extra_body into that upstream request. If the same upstream field exists in both places, extra_body wins.

Prefer the portable fields for n, image_size, aspect_ratio, and reference images. If extra_body changes the final upstream count or size, LLMAPI bills by the final parsed image tier. Unit prices still come from the task model pricing configuration.

json

{
  "model": "gemini-3.1-flash-image",
  "modality": "image",
  "params": {
    "model": "gemini-3.1-flash-image",
    "prompt": "Create a product image using this object.",
    "images": [{ "image_url": "data:image/png;base64,BASE64_IMAGE" }],
    "n": 1,
    "image_size": "2K",
    "aspect_ratio": "16:9",
    "extra_body": {
      "generationConfig": {
          "temperature": 0.7
      }
    }
  }
}

Video Common Contract

Video tasks use prompt, duration, resolution, aspect_ratio, generate_audio, inputs, and provider_options. prompt, duration, resolution, and aspect_ratio are required. The public parser requires a positive integer duration and non-empty strings, but the model list does not currently enumerate supported video values. Prefer common fields and place protocol-specific parameters in provider_options; video does not accept the image protocol's extra_body.

json

{
  "model": "seedance-video-model",
  "modality": "video",
  "params": {
    "prompt": "Transition naturally from morning to night with a slow push-in",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true,
    "inputs": [
      {
        "id": "start",
        "type": "image",
        "role": "first_frame",
        "url": "https://example.com/start.png"
      },
      {
        "id": "end",
        "type": "image",
        "role": "last_frame",
        "url": "https://example.com/end.png"
      }
    ]
  }
}

For video, images may use first_frame, last_frame, or reference; video and audio inputs may use reference. The request may contain at most 16 inputs. A route whose adapter cannot build the complete input and parameter combination is skipped. Fields are never silently discarded.

Use params.provider_options only for protocol-specific controls that the common fields cannot express. It cannot override public fields such as model, prompt, duration, resolution, aspect_ratio, or inputs. Do not put credentials in task parameters. Protocol-specific options may reduce the set of capable routes. Current video channels require input assets to use publicly reachable HTTP(S) URLs.

3D Common Contract

The 3D V1 public parser accepts prompt, inputs, output_format, and extra_body. Provide at least one of prompt or inputs; inputs are limited to type=image, role=reference. This describes the retained common contract only. No 3D adapter is currently registered, so the example cannot be submitted to an executable 3D model yet.

json

{
  "model": "3d-generation-model",
  "modality": "3d",
  "params": {
    "prompt": "Create a web-preview-ready 3D model from the reference image",
    "inputs": [
      {
        "id": "product",
        "type": "image",
        "role": "reference",
        "url": "https://example.com/product.png"
      }
    ],
    "output_format": "glb",
    "extra_body": {
      "texture_quality": "high"
    }
  }
}

When present, output_format must be a non-empty string. There is currently no advertised output-format whitelist and no 3D adapter. Upstream-specific mesh, texture, rigging, or animation controls remain in extra_body for a future adapter to validate.

`inputs[]` Fields

Field	Type	Required	Description
`id`	string	No	Unique name within the task. Use letters, digits, `_`, or `-`.
`type`	string	Yes	`image`, `video`, or `audio`, depending on modality and model capabilities.
`role`	string	Yes	`reference`, `first_frame`, or `last_frame`, depending on modality and model capabilities.
`url`	string	Yes	A public HTTP(S) URL reachable by the upstream provider.

Video and 3D public inputs reject Data URLs, local paths, and platform-internal asset addresses. The parser accepts at most 16 inputs. It does not currently publish or enforce per-model file-size, file-format, or media-duration limits.

Response — 202 Accepted

json

{
  "id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "status": "queued",
  "modality": "image",
  "model": "gpt-image-2",
  "created_at": "2026-06-22T03:10:00Z",
  "estimated_cost": 0.1
}

Field	Description
`id`	Task ID. Use this for polling and asset downloads.
`status`	`queued` for a new task. An idempotency replay returns the existing task's current status.
`estimated_cost`	Estimated charge in USD. Reserved at submission and settled or released when the task finishes.

Use the returned id with GET /v1/tasks/{id} to query status. To receive task updates, connect to GET /v1/tasks/events.

Errors

Status	Cause
`400`	Invalid request body or unsupported parameter. The `error.message` field names the offending field.
`400 TASK_NO_CAPABLE_ROUTE`	The available routes do not support the requested modality, parameters, or input-asset combination.
`401`	Missing or invalid API key.
`403`	API key is not enabled for Task API, balance is insufficient, or subscription billing is not supported for tasks.
`413`	Request body exceeds the configured server limit.
`429`	Queue or rate limit exceeded. Retry with exponential backoff.
`503`	Task API is paused, pricing is unavailable, storage is unavailable, or the service is temporarily unavailable.

Submit a Task ​

Request Body ​

Image Generation ​

Edit with Reference Image ​

Size Parameters ​

Advanced Extension Parameters ​

Video Common Contract ​

3D Common Contract ​

inputs[] Fields ​

Response — 202 Accepted ​

Errors ​

Submit a Task

Request Body

Image Generation

Edit with Reference Image

Size Parameters

Advanced Extension Parameters

Video Common Contract

3D Common Contract

`inputs[]` Fields

Response — 202 Accepted

Errors