> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt Optimizer API: Improve Generation Prompts

> APIXO prompt optimization API for image and video generation: expand short prompts into detailed, model-ready instructions.

## 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:

```text theme={null}
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:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Submit requests also require:

```http theme={null}
Content-Type: application/json
```

## Copy-paste async quickstart

```bash theme={null}
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:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}
```

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

## Poll for result

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

Success response:

```json theme={null}
{
  "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`:

```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const optimizedPrompt = payload.outputs?.[0];
```

## Request body

```json theme={null}
{
  "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

<ParamField body="request_type" type="string" required default="async">
  Result delivery mode. Use `async` for polling with `statusTask`, or `callback` for webhook delivery.
</ParamField>

<ParamField body="callback_url" type="string">
  Required when `request_type` is `callback`. Must be a callback URL that can receive the final task payload. See [Webhooks](/docs/api-reference/webhooks).
</ParamField>

<ParamField body="input" type="object" required>
  Prompt Optimizer input parameters.

  <Expandable title="properties">
    <ParamField body="mode" type="string" default="optimizer">
      Optimization mode. The only supported value is `optimizer`. If omitted, the backend defaults to `optimizer`.
    </ParamField>

    <ParamField body="prompt" type="string" required>
      Raw prompt text to optimize. Must be non-empty and cannot exceed `5000` characters.
    </ParamField>

    <ParamField body="style" type="string" default="default">
      Optimization style. Supported values: `default`, `artistic`, `photographic`, `technical`, `anime`, `realistic`.
    </ParamField>

    <ParamField body="target_mode" type="string" default="image">
      Target generation type for the optimized prompt. Supported values: `image`, `video`.
    </ParamField>
  </Expandable>
</ParamField>

## Response format

### Submit task response

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

<ResponseField name="code" type="integer">
  API status code. `200` means the task was accepted.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message.
</ResponseField>

<ResponseField name="data.taskId" type="string">
  Unique task identifier used with the status endpoint.
</ResponseField>

### Status response fields

<ResponseField name="taskId" type="string">
  Unique task identifier.
</ResponseField>

<ResponseField name="state" type="string">
  Current task state: `pending`, `processing`, `success`, or `failed`.
</ResponseField>

<ResponseField name="resultJson" type="string">
  JSON string containing optimized prompt output. Present when `state` is `success`.
</ResponseField>

<ResponseField name="failCode" type="string">
  Machine-readable failure code. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="failMsg" type="string">
  Human-readable failure message. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="createTime" type="integer">
  Task creation timestamp in Unix milliseconds.
</ResponseField>

<ResponseField name="completeTime" type="integer">
  Task completion timestamp in Unix milliseconds. Present after completion.
</ResponseField>

<ResponseField name="costTime" type="integer">
  Processing duration in milliseconds when available.
</ResponseField>

## Webhook callback mode

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

```bash theme={null}
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](/docs/api-reference/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](https://apixo.ai/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](/docs/api-reference/errors) for the full error reference.

## Related links

* [Generation API Overview](/docs/models)
* [Text & Utilities](/docs/models/text)
* [Generate Task](/docs/api-reference/generate-task)
* [Status Task](/docs/api-reference/status-task)
* [Webhooks](/docs/api-reference/webhooks)
* [Error Codes](/docs/api-reference/errors)
* [Parameter Specification](/docs/api-reference/parameters)
* [Pricing](https://apixo.ai/pricing)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.