> ## 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 AI Guide: Preserve Intent and Exact Text

> Prepare Prompt Optimizer requests with exact-text extraction, faithful creative briefs, ordered references and complete AI calling examples.

Use the same [Prompt Optimizer endpoint and asynchronous flow](https://apixo.ai/docs/models/text/prompt-optimizer.md) as ordinary callers. `protected_text` and `creative_brief` are optional inputs for AI assistants, MCP clients and calling plugins. They require no separate identity or endpoint. Ordinary users can express their requirements in `prompt` and `reference_notes`.

## Prepare the request

1. Preserve the user's complete request in `prompt`, including constraints, exceptions, quantities and permitted edits. Do not shorten it by moving requirements into advanced fields.
2. Choose the intended `target_model` and `generation_mode`. Unknown target names are accepted; select a video mode explicitly for unknown video targets. Optimization returns text and does not start media generation.
3. Attach references only through ordered `image_urls` (up to 4 public HTTPS URLs). Use image numbers starting at 1. Describe only known reference uses in `reference_notes`; do not guess image contents or permission to change them.
4. Extract exact user-required wording into `protected_text` only when appropriate.
5. Optionally organize already stated creative requirements in `creative_brief`. Leave missing information absent.
6. Submit once; poll the returned task ID or await callback. Read `data.state` before parsing `data.resultJson`. Review the output before requesting media generation separately.

## Exact text with protected\_text

Use this optional array for dialogue, lyrics, visible lettering, labels, titles or other wording the user requires verbatim. Each of at most 32 strings must be nonblank, at most 1000 characters and occur exactly in `prompt`.

* Copy the actual substring with its original case, spacing, punctuation and language. Do not translate or paraphrase it.
* Do not invent a missing name or label, lock ordinary description, or protect the entire prompt to avoid deciding.
* Omit the field if no exact-text requirement exists. Keep the complete original requirement in `prompt` after extraction.
* For `Keep the cup label SPRING TEA unchanged`, the protected item is `SPRING TEA`.

Preserving exact wording does not guarantee the entire output is semantically correct; review all constraints too.

## Existing requirements with creative\_brief

This optional object accepts only the following string fields, each at most 1000 characters:

| Field | What to extract |
| - | - |
| `scene` | Stated setting and environment. |
| `camera` | Stated framing, viewpoint or camera movement. |
| `style` | Stated visual style. |
| `action_details` | Stated actions, sequence and qualifying details. |
| `audio` | Stated sound or dialogue requirements. |

Do not add a setting, shot, style, action, sound or plot event to fill an unused field. Keep these fields consistent with `prompt` and `reference_notes`. Do not turn local or conditional restrictions into global ones: no dialogue does not mean silence; no background music does not remove ambient sound; no additional text does not remove existing labels.

`creative_brief.style` is a supported child field. Ordinary style, camera and shot requirements belong in `prompt`.

## Image order and language

Image 1 is the editing base in `image-to-image`; later images are references. `image-to-video` has one starting frame. `first-and-last-frames` requires exactly two images in start/end order and an explicit mode. Two images alone imply reference generation, not endpoints. Notes cannot reverse these responsibilities. Reordering images requires updating image numbers throughout the request.

Explain what each reference contributes, what must stay unchanged and what must not be copied. If no image is supplied, notes alone do not attach one. Unknown reference uses should remain unspecified.

Use `language` explicitly for a required descriptive output language. Preserve supplied dialogue, lyrics, lettering, coordinate tags and numeric constraints. See the main guide's [image language policy](https://apixo.ai/docs/models/text/prompt-optimizer.md#image-language-selection-and-preservation) and [video language policy](https://apixo.ai/docs/models/text/prompt-optimizer.md#video-language-selection-and-preservation) for `auto`. A returned prompt is one string; some targets use named sections within it.

## Complete request examples

Submit each body to `POST https://api.apixo.ai/api/v1/generateTask/prompt-optimizer` with `Authorization: Bearer YOUR_API_KEY` and `Content-Type: application/json`. Replace placeholder URLs with accessible files and your own callback receiver.

### Minimal image prompt

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "optimizer",
    "prompt": "A ceramic cup on a wooden table in soft window light."
  }
}
```

### AI-assisted editing with exact text

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "optimizer",
    "prompt": "Use image 1 as the editing base. Replace only the background with the wooden table environment in image 2. Keep the cup shape, color and label SPRING TEA unchanged. Use natural photography, a fixed camera and a medium shot. Do not add people or text.",
    "target_model": "generic-image",
    "generation_mode": "image-to-image",
    "language": "en",
    "image_urls": [
      "https://images.example.com/cup.png",
      "https://images.example.com/table.png"
    ],
    "reference_notes": "Image 1 is the editing base; preserve the cup and its label. Image 2 supplies only the table background; do not copy its people or lettering.",
    "protected_text": [
      "SPRING TEA"
    ],
    "creative_brief": {
      "camera": "Fixed camera, medium shot",
      "style": "Natural photography"
    }
  }
}
```

### Video reference with scoped audio instructions

```json theme={null}
{
  "request_type": "callback",
  "callback_url": "https://your-server.example.com/optimization-result",
  "input": {
    "mode": "optimizer",
    "prompt": "Use the cup in image 1 as the product reference. Show the cup on a wooden table for 6 seconds with one continuous fixed-camera shot. Keep the label SPRING TEA unchanged. No dialogue or background music; retain the ambient rain sound.",
    "target_model": "generic-video",
    "generation_mode": "reference-to-video",
    "language": "en",
    "duration": 6,
    "image_urls": [
      "https://images.example.com/cup.png"
    ],
    "reference_notes": "Image 1 supplies only the cup appearance and label; it is not a required starting frame.",
    "protected_text": [
      "SPRING TEA"
    ],
    "creative_brief": {
      "scene": "Cup on a wooden table",
      "camera": "One continuous fixed-camera shot",
      "audio": "No dialogue or background music; retain ambient rain sound"
    }
  }
}
```

### Explicit first and last frames

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "optimizer",
    "prompt": "Start at image 1 and end at image 2. Show the door opening slowly while keeping the camera fixed.",
    "target_model": "generic-video",
    "generation_mode": "first-and-last-frames",
    "image_urls": [
      "https://images.example.com/door-closed.png",
      "https://images.example.com/door-open.png"
    ],
    "reference_notes": "Image 1 is the starting frame; image 2 is the ending frame."
  }
}
```

## Read the result

Save `data.taskId` from acceptance and query `GET /api/v1/statusTask/prompt-optimizer?taskId={taskId}` using an API key from the same account, or await the callback. While processing, do not resubmit. When successful, parse `data.resultJson` once and read `outputs[0]`. If failed, read `failCode` and `failMsg`; an outer `code=200` is not a successful optimization result.

Poll after about 5 seconds and at intervals of 5 seconds or longer. A timeout is not proof that the task was never created. Check an existing task before submitting a replacement. Media generation remains a separate operation.


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