Task API

Task API is LLMAPI's unified interface for long-running media jobs. Clients submit a JSON task, receive a task ID, and read the final result through polling or Server-Sent Events. The common contract supports model configuration and asset responses for image, video, and 3d modalities.

Current availability

Image and video adapters are available. Each channel selects exactly one adapter.

The public 3D request and channel-backed routing structures are retained, but no 3D adapter is registered yet. Therefore, no 3D model is currently executable or returned by GET /v1/tasks/models.

Endpoints

Method	Path	Description
POST	/v1/tasks	Submit a task.
POST	/v1/tasks/{id}/cancel	Cancel a queued task.
GET	/v1/tasks/{id}	Retrieve status and result.
GET	/v1/tasks/{id}/assets/{index}	Download a result asset.
GET	/v1/tasks/events	Subscribe to task updates via SSE.
GET	/v1/tasks/models	List each model's effective price and parameter constraints for the current key.

Task API keys can only call /v1/tasks*, plus POST /v1/images/generations and POST /v1/images/edits for OpenAI Images compatible synchronous calls. General model API keys cannot submit tasks.

Lifecycle

Status	Meaning
queued	Accepted and waiting to be processed.
running	Processing.
succeeded	Finished successfully. Result assets are available.
failed	Failed.
timeout	Timed out.
canceled	Canceled before running.

Modalities

modality	Public capabilities	Result assets[].kind	Current status
image	Text-to-image, references, edit/repaint where supported	image	Available
video	Text-to-video, first/last frames, multi-asset references, native audio where supported	video, optionally audio or image	Available through configured video channels
3d	Text or reference-image to 3D model	model, optionally image or texture files	Adapter not available yet

Billing and Usage

At submission, LLMAPI reserves the estimated_cost under the effective plan for the requested model on the current key. A successful task settles actual_cost; a lower actual amount returns the difference, while a higher amount deducts the difference. Failed, timed-out, and canceled tasks release the reservation and are not charged.

The current user pricing modes are image size matrix (image_matrix), video duration (video_duration), and per request (per_request). Video charges use the task's standardized duration field and do not use token usage returned by the upstream provider. Async tasks also do not currently write traditional usage_logs; use the cost fields in the task response and admin task detail instead.

Key Rules

• Use a Task API key.
• A key may select a Task Plan per model. Models without an explicit selection use that model's default plan.
• Do not send a plan parameter or modify model names. Use GET /v1/tasks/models to discover what the current key can use.
• If one model's selection becomes invalid, only that model returns to its own default plan.
• Put model-specific request fields in params.
• If params.model is present, it must match the top-level model.
• LLMAPI selects an available route according to the effective plan for the requested model.
• Treat GET /v1/tasks/models as the only availability source; do not infer modality or capabilities from a model name.

Error Format

Task API business errors use this JSON shape. Authentication failures still return authentication_error:

{
  "error": {
    "type": "TASK_INVALID_REQUEST",
    "message": "params is required"
  }
}

Common task errors:

Error type	HTTP status	Meaning
authentication_error	401	API key is missing or invalid.
TASK_SCOPE_REQUIRED	403	The API key is not enabled for Task API.
TASK_INVALID_REQUEST	400	Request body or parameters are invalid.
TASK_UNSUPPORTED_MODEL	400	The requested model is not available for Task API.
TASK_UNSUPPORTED_ADAPTER	400	The selected model cannot run this task type.
TASK_PRICING_UNAVAILABLE	503	Pricing is not configured for the requested parameters.
TASK_STORAGE_UNAVAILABLE	503	Result asset storage is unavailable.
TASK_INSUFFICIENT_BALANCE	403	Balance is insufficient for the estimated task cost.
TASK_QUEUE_LIMIT_EXCEEDED	429	The user or API key reached the queued task limit.
TASK_NOT_FOUND	404	Task or asset does not exist, or is not accessible with this key.