Prompt Optimizer AI Guide: Preserve Intent and Exact Text

Use the same Prompt Optimizer endpoint and asynchronous flow 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

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.
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.
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.
Extract exact user-required wording into protected_text only when appropriate.
Optionally organize already stated creative requirements in creative_brief. Leave missing information absent.
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 and video language policy 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

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

AI-assisted editing with exact text

{
  "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

{
  "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

{
  "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.

​Prepare the request

​Exact text with protected_text

​Existing requirements with creative_brief

​Image order and language

​Complete request examples

​Minimal image prompt

​AI-assisted editing with exact text

​Video reference with scoped audio instructions

​Explicit first and last frames

​Read the result