Prompt Optimizer API

Overview

Prompt Optimizer is an asynchronous text utility API. Submit a raw prompt, choose an optimization style and target media type, then poll the task for the optimized prompt output.

Capability	Value
Model ID	`prompt-optimizer`
Mode	`optimizer`
Prompt length	1-5000 characters
Styles	`default`, `artistic`, `photographic`, `technical`, `anime`, `realistic`
Target modes	`image`, `video`
Billing	Fixed per use

Endpoint and authentication

Base URL:

https://api.apixo.ai/api/v1

Method	Endpoint	Purpose
`POST`	`/generateTask/prompt-optimizer`	Submit a prompt optimization task
`GET`	`/statusTask/prompt-optimizer?taskId={taskId}`	Poll task status and retrieve results

All requests require your APIXO API key:

Authorization: Bearer YOUR_API_KEY

Submit requests also require:

Content-Type: application/json

Copy-paste async quickstart

curl -X POST "https://api.apixo.ai/api/v1/generateTask/prompt-optimizer" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "optimizer",
      "prompt": "a cinematic night street in heavy rain, neon reflections, dramatic lens flare",
      "style": "photographic",
      "target_mode": "video"
    }
  }'

Successful response:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}

Save the taskId; you need it to poll for the final result.

Poll for result

curl -X GET "https://api.apixo.ai/api/v1/statusTask/prompt-optimizer?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success response:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"outputs\":[\"optimized prompt text\"]}",
    "createTime": 1767965610929,
    "completeTime": 1767965652317,
    "costTime": 41388
  }
}

Parse resultJson after state becomes success:

const payload = JSON.parse(data.resultJson);
const optimizedPrompt = payload.outputs?.[0];

Request body

{
  "request_type": "async",
  "callback_url": "https://your-server.com/webhooks/apixo",
  "input": {
    "mode": "optimizer",
    "prompt": "a cinematic night street in heavy rain, neon reflections, dramatic lens flare",
    "style": "photographic",
    "target_mode": "video"
  }
}

Parameters

string

default:"async"

required

Result delivery mode. Use async for polling with statusTask, or callback for webhook delivery.

string

Required when request_type is callback. Must be a callback URL that can receive the final task payload. See Webhooks.

object

required

Prompt Optimizer input parameters.

Show properties

string

default:"optimizer"

Optimization mode. The only supported value is optimizer. If omitted, the backend defaults to optimizer.

string

required

Raw prompt text to optimize. Must be non-empty and cannot exceed 5000 characters.

string

default:"default"

Optimization style. Supported values: default, artistic, photographic, technical, anime, realistic.

string

default:"image"

Target generation type for the optimized prompt. Supported values: image, video.

Response format

Submit task response

POST /generateTask/prompt-optimizer returns a task ID when the task is accepted:

integer

API status code. 200 means the task was accepted.

string

Human-readable status message.

string

Unique task identifier used with the status endpoint.

Status response fields

string

Unique task identifier.

string

Current task state: pending, processing, success, or failed.

string

JSON string containing optimized prompt output. Present when state is success.

string

Machine-readable failure code. Present when state is failed.

string

Human-readable failure message. Present when state is failed.

integer

Task creation timestamp in Unix milliseconds.

integer

Task completion timestamp in Unix milliseconds. Present after completion.

integer

Processing duration in milliseconds when available.

Webhook callback mode

Use callback mode when your backend should receive the final result automatically instead of polling.

curl -X POST "https://api.apixo.ai/api/v1/generateTask/prompt-optimizer" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "callback",
    "callback_url": "https://your-server.com/webhooks/apixo",
    "input": {
      "mode": "optimizer",
      "prompt": "a simple product photo, premium look",
      "style": "photographic",
      "target_mode": "image"
    }
  }'

See Webhooks for delivery requirements and retry behavior.

Billing

Prompt Optimizer is billed per call.

Billing dimension	Value
Unit	`PER_USE`
APIXO price	`$0.001 / use`
Parameter-based tiers	None

For current route and market comparison pricing, see Pricing.

Latency and polling

Prompt Optimizer tasks are asynchronous. Actual latency varies by prompt length and queue load.

Use case	Recommended first poll	Poll interval
Normal prompt optimization	3s-5s after task creation	3s-5s
Batch or production workloads	Prefer callback mode	If polling, use 5s or longer

Errors and troubleshooting

HTTP errors

Code	Meaning	What to do
`400`	Invalid request body, parameter type, or value	Fix the request before retrying
`401`	Missing or invalid API key	Check the `Authorization` header
`402`	Insufficient balance or quota	Add balance or switch account/key
`403`	Key or route cannot access the model	Check permissions and route strategy
`404`	Task not found	Verify the `taskId` and model ID
`429`	Rate limit or concurrency limit reached	Retry with exponential backoff
`500`	Server or unmapped model error	Retry with backoff
`502`	Model service error	Retry with backoff
`504`	Model service timeout	Retry or use callback mode for long-running jobs

Request validation

Condition	Backend behavior
Missing `input`	Returns `The required parameter {{input}} is missing.`
Invalid `mode`	Returns `Invalid mode type. Supported: optimizer`
Missing or empty `prompt`	Returns a missing-parameter or validation error
Prompt exceeds `5000` characters	Returns a length error
Invalid `style`	Returns the supported style list
Invalid `target_mode`	Returns `The parameter {{target_mode}} must be either 'image' or 'video'.`

See Error Codes for the full error reference.

​Overview

​Endpoint and authentication

​Copy-paste async quickstart

​Poll for result

​Request body

​Parameters

​Response format

​Submit task response

​Status response fields

​Webhook callback mode

​Billing

​Latency and polling

​Errors and troubleshooting

​HTTP errors

​Request validation

​Related links

Overview

Endpoint and authentication

Copy-paste async quickstart

Poll for result

Request body

Parameters

Response format

Submit task response

Status response fields

Webhook callback mode

Billing

Latency and polling

Errors and troubleshooting

HTTP errors

Request validation

Related links