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

> APIXO prompt optimization API for image and video generation prompts

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