Prompt Optimizer API: Image and Video Prompt Optimization

Convert image or video instructions into one optimized prompt. This asynchronous API returns text; generating media is a separate request.

Capability	Value
Model ID	`prompt-optimizer`
Mode	`optimizer`
Default target	Image optimization
References	Up to 4 ordered HTTPS image URLs
Billing	Fixed per optimization task

Endpoints

Base URL:

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

Method	Endpoint	Purpose
`POST`	`/generateTask/prompt-optimizer`	Create an optimization task
`GET`	`/statusTask/prompt-optimizer?taskId={taskId}`	Read task status and optimized text

Authentication

Use Authorization: Bearer YOUR_API_KEY. POST requests also require Content-Type: application/json. Query a task using an API key belonging to the account that created it.

Request Body

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

The minimal request defaults to image optimization. Choose generation_mode explicitly for video, references or first-and-last frames. AI callers can also use the advanced calling guide.

Parameters

string

default:"async"

Supported values: async, callback. Use async for polling or callback for final notification. Sync and streaming are unsupported.

string

Required when request_type is callback. Use a public HTTPS receiver. See Webhooks.

object

required

Prompt optimization returns text, not generated images or videos. AI callers: preserve the full user request in prompt, choose target_model and generation_mode, attach ordered image_urls, describe only known reference uses in reference_notes, then optionally extract protected_text and creative_brief. These optional fields use the same endpoint and identity as ordinary requests; do not require users to fill them. Never remove requirements from prompt after extracting them. Do not invent image contents, reference permissions, names, camera moves, plot events or audio. Preserve conditions, exceptions, quantities and the scope of restrictions: no dialogue does not mean silence, and no new text does not remove existing labels. Submit once, save data.taskId, then poll or await callback; check an existing task before resubmitting after a timeout. Poll with an API key belonging to the creating account. data.state is processing, success or failed. Only on success, parse data.resultJson once and read outputs[0], a single prompt string (possibly containing named sections), not a media URL. The result has a 16000-character limit. A successful status query can have code=200 while data.state=failed; inspect state, failCode and failMsg. Charged failed tasks are refunded. Review the output before a separate generation request; optimization does not guarantee semantic correctness or media quality.

Show properties

string

default:"optimizer"

Supported value: optimizer. This is the optimization API mode; generation_mode separately describes the intended image or video task.

string

required

Required nonblank original request, at most 5000 characters. Preserve the full user intent, exact wording, quantities, conditions, exceptions, allowed edits and what must remain unchanged. Put camera, visual style and single/multiple-shot requirements here. Extracting protected_text or creative_brief must not remove the corresponding requirements from prompt.

string

Intended generation model for the returned text, at most 80 characters. This does not submit a generation request. This field is not an allowlist: unknown names are accepted and preserved, and uncovered targets or modes use general image/video guidance. With neither target nor generation_mode, the target defaults to generic-image. An explicit video mode without a target uses generic-video. An unknown target without an explicit mode defaults to image optimization, so select a video generation_mode explicitly for unknown video targets. Generation-model image counts, duration limits and native modes do not become optimizer restrictions.

string

Supported values: text-to-image, image-to-image, reference-to-image, text-to-video, image-to-video, reference-to-video, first-and-last-frames. Select explicitly when intent is known; this determines the image/video task family even when the target name suggests another family. Text modes accept no images. image-to-image requires at least one image: image 1 is the editing base and the rest are references. image-to-video requires exactly one starting frame. Reference modes require at least one reference; do not assume its purpose. first-and-last-frames requires exactly two images in start/end order and must be selected explicitly. When omitted, zero images select text generation, one selects editing or image-to-video according to the target family, and multiple select reference generation; two images alone never imply first-and-last-frames.

string

default:"auto"

Supported values: auto, zh, en, fr, de, es, it, ja, ko, ru, tr, pl. Sets the descriptive output language, not the language of supplied dialogue, lyrics or visible lettering: preserve those exactly. Set an explicit value when a particular language is required. With auto, covered image/video targets consider explicit language instructions and the main descriptive language, excluding exact labels, quotes, URLs and coordinates. Seedance/Wan video guidance uses supported descriptive languages, defaulting to Chinese if unidentified; minimax-h3-LoRA otherwise defaults to English. Covered image guidance follows the descriptive language; seedream-4-5, seedream-5-0 and qwen-image-edit-LoRA conservatively use English for recognized languages other than Chinese/English unless explicitly selected. Unregistered targets use general Chinese/English inference. See the main guide for target coverage.

integer

Optional intended video duration, an integer from 1 through 120 seconds. It is optimization context, not a generation API setting or guarantee. Omit for image tasks; image tasks ignore it before validation. Do not invent a duration the user did not request.

array

Ordered array of public HTTPS URL strings; default is an empty array, with at most 4 images regardless of the target generation model limits. Each string must be nonblank, at most 8192 characters, without surrounding whitespace, URL credentials or private/local addresses. Base64 and image objects are unsupported. Image numbers start at 1 and follow array order. Editing uses image 1 as the base; image-to-video uses the sole image as the start; first-and-last-frames uses images 1 and 2 as start and end. Reference notes cannot reverse these responsibilities. If reordering URLs, update every image number in prompt and reference_notes. Supply actual image addresses; notes alone do not attach images.

string

Optional reference-use instructions, at most 3000 characters; default is an empty string. For each known use, name the image number (starting at 1), what it contributes, what must be preserved and what must not be copied. Example: Image 1 supplies the cup shape and label; image 2 supplies only the background and lighting, not its people or lettering. Keep notes consistent with prompt, image order and generation_mode. For editing, describe only authorized changes to image 1; for endpoint frames, preserve start/end order. AI callers must preserve existing notes and summarize only user-stated uses, without inventing identities, image contents or edit permissions. Omit when no images or no known additional reference instructions are present.

array

Optional AI-assisted exact-text extraction; default is an empty array. At most 32 nonblank strings, at most 1000 characters each; every item must occur verbatim in prompt. Use only for user-required dialogue, lyrics, visible lettering, titles, labels or exact wording. Copy the actual substring, preserving its case, spacing, punctuation and language; do not translate, paraphrase or invent missing text. If prompt says Keep the cup label SPRING TEA unchanged, use [“SPRING TEA”]. Do not lock the whole prompt or ordinary descriptive sentences merely to avoid deciding. Omit when no exact-text requirement exists. Keep the full original requirement in prompt after extraction, and review the complete output even when exact text is preserved.

object

Optional AI-assisted organization of requirements already stated by the user; default is an empty object. Only scene, camera, style, action_details and audio are allowed; each present value must be a string of at most 1000 characters. scene means stated setting/environment; camera means stated framing/viewpoint/movement; style means stated visual style; action_details means stated actions, order and conditions; audio means stated sound/dialogue requirements. Leave missing information and unused keys absent. Do not add a setting, camera move, style, action, sound or plot event to fill the object. Preserve local and conditional restrictions rather than making them global; no dialogue does not mean silence. Keep these fields consistent with prompt and reference_notes, and do not remove extracted requirements from prompt. Example for a request explicitly specifying both: {"camera":"Fixed camera, medium shot","style":"Natural photography"}. creative_brief.style is supported; write ordinary style instructions in prompt.

Generation modes and image order

generation_mode	Image requirement and responsibility
`text-to-image`, `text-to-video`	No images.
`image-to-image`	1–4 images; image 1 is the editing base, the rest are references.
`image-to-video`	Exactly one image, used as the starting frame.
`reference-to-image`, `reference-to-video`	1–4 references; explain their intended uses.
`first-and-last-frames`	Exactly two images: starting frame first, ending frame second. Select this mode explicitly.

Writing reference notes

Number images from 1 in the order of image_urls. Explain what each contributes, what must remain unchanged and what must not be copied. Notes cannot reverse editing-base or start/end responsibilities. If the order changes, update all image numbers in the instructions. Unknown reference uses should remain unspecified.

Targets with expression guidance

Family	`target_model` values
General image	`generic-image`
Video	`seedance-2-5`, `seedance-1-5-pro`, `wan-3-0-video`, `seedance-2-0`, `seedance-2-0-fast`, `seedance-2-0-mini`, `wan-2-7-video`, `wan-2-7-video-LoRA`, `minimax-h3-LoRA`
Image	`flux-2`, `flux-3-image`, `flux-kontext`, `gpt-image-1`, `gpt-image-2`, `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`, `z-image-LoRA`, `z-image-LoRA-pro`, `qwen-image-edit-LoRA`, `grok-image`, `midjourney`, `minimax-image-01`, `runway-gen4-image`, `runway-gen4-image-turbo`, `nano-banana-2`, `nano-banana-2-1`, `nano-banana-pro`, `nano-banana`, `qwen`, `qwen-2-image`, `qwen-image-3-0`, `qwen-image-3-0-pro`, `seedream-4-0`, `seedream-4-5`, `seedream-5-0`, `seedream-5-0-pro`, `wan-2-5-image`, `wan-2-6-image`, `wan-2-7-image`

This list is guidance coverage, not an input allowlist. Other target names also work through general optimization. The optimizer accepts at most 4 images; a later generation request has its own independent limits. Target-specific expression guidance is selected automatically. The optimized result has the optimizer’s own 16000-character budget; generation-model image counts, native modes and prompt lengths do not block optimization.

Image language selection and preservation

The following targets use image-specific preservation checks in every supported output language: seedream-5-0-pro, seedream-4-5, gpt-image-2, nano-banana-2, seedream-5-0 (Seedream 5.0 Lite), nano-banana-pro, gpt-image-2.5-sunburst, and qwen-image-edit-LoRA in its editing mode.

An explicit language takes priority. With auto, an explicit request for the final prompt’s language is considered next, followed by the main descriptive language. Exact labels, quoted text, URLs and supplied coordinates do not determine that language.
For seedream-4-5, seedream-5-0 and qwen-image-edit-LoRA, auto conservatively uses English when the description is recognized as a supported language other than Chinese or English. This does not override an explicitly selected language. When no descriptive language can be identified, Chinese is used.
Same-language source instructions remain complete in the final prompt. Translations retain exact lettering, supplied coordinate tags and numeric constraints. Each reference keeps its stated responsibility; local edits preserve everything outside the authorized change.
Other image targets retain their existing language behavior. Generation-model limits do not become optimizer input restrictions.

Video language selection and preservation

An explicit language takes priority. With auto, an explicit request for the final prompt’s language in the original text is considered next.
For the listed Seedance and Wan video targets, auto follows the main descriptive language among supported languages. When it cannot be identified, Chinese is used. Quoted text, exact labels and URLs do not determine the descriptive language.
For minimax-h3-LoRA, auto otherwise uses English. Explicitly selected languages remain supported. Descriptive language does not translate supplied dialogue, lyrics or visible lettering.
Image targets outside the image-specific list above and unregistered targets retain the general Chinese/English inference.
Wan 2.7 and Wan 2.7 LoRA share expression guidance. No custom LoRA trigger words are added.
Conditions, exceptions and the scope of restrictions must remain intact. No dialogue does not mean silence; no background music does not remove ambient sound; no additional text does not remove existing labels.
H3 returns one prompt string with three named sections for base/frame tasks or six for reference tasks. Section identifiers remain in English. No unspecified music or sound is invented to fill empty sections.

Example

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 ceramic cup on a wooden table in soft window light."}}'

For ordered editing references and exact label preservation, send:

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

Replace example image addresses with your own accessible files. AI calling examples also cover video references and first-and-last frames.

Response

Accepted task:

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

Poll the saved task ID:

curl 'https://api.apixo.ai/api/v1/statusTask/prompt-optimizer?taskId=task_example' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Successful result:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_example",
    "state": "success",
    "resultJson": "{\"outputs\":[\"A ceramic cup on a wooden table in soft window light.\"]}",
    "createTime": 1792108800000,
    "completeTime": 1792108815000,
    "costTime": 15000
  }
}

After data.state becomes success, read JSON.parse(data.resultJson).outputs[0]. The result is one text string, at most 16000 characters, with no generated media URLs or separate analysis fields. A clear original prompt may be retained when it already meets the requirements.

Status Response Fields

Field	Meaning
`taskId`	Task identifier returned at submission.
`state`	`processing`, `success` or `failed`.
`resultJson`	Success-only JSON string containing `{"outputs":["one optimized prompt"]}`.
`failCode`, `failMsg`, `mappedCode`	Failure details. Optimization failure uses `prompt_optimization_failed`, an English message and mapped code `500`.
`createTime`, `completeTime`	Unix milliseconds; completion time is present for terminal results.
`costTime`	Completion time minus creation time; terminal timing remains stable across queries.

The outer code: 200 means the query succeeded; inspect data.state for the task outcome. A failed task does not return a successful resultJson. For callback delivery, set request_type="callback" and a top-level callback_url; the final notification uses the same result envelope. See Webhooks.

Error Codes

HTTP code	Meaning
400	Invalid parameter type, value, image count or URL, or conflicting input requirements.
401 / 403	Authentication or access denied.
402	Insufficient balance or quota.
404	Task unavailable to the authenticated account.
429	Rate or concurrency limit reached.
500 / 502 / 504	Service failure or timeout. Check the existing task before submitting again.

Unknown target names are accepted; they are not validation errors. See Common errors.

Billing

New non-LLM requests use 1 credit = $0.001. Calculate the full amount, including billable quantity and add-ons, apply the applicable account discount, then round the request total upward to the next whole credit. Agreed fixed unit prices retain their precision and replace the standard price and discount; final rounding still applies. See credit conversion and rounding. The standard price is USD $0.002 per optimization task (PER_USE). Image count, intended video duration and reference mode do not add pricing tiers. Account pricing and discounts may affect the actual quote. Charged tasks that fail are refunded. Image/video generation is a separate request and is not included. See API pricing.

Latency and polling

Use case	Recommended first poll	Poll interval
Prompt optimization	About 5 seconds after acceptance	5 seconds or longer

Account and API-key limits apply. No fixed throughput or completion-time guarantee is specified. Use callback mode for backend workflows. Save the task ID and check its status instead of repeatedly creating a new task.

MCP integration

The complete model schema declares result decoding in mcp.result and supported file bindings in mcp.attachments. These are client integration metadata, not generation input parameters. Attachment paths: image_urls. Preserve the user’s file order. Model parameter validation remains on the API.

​Endpoints

​Authentication

​Request Body

​Parameters

​Generation modes and image order

​Writing reference notes

​Targets with expression guidance

​Image language selection and preservation

​Video language selection and preservation

​Example

​Response

​Status Response Fields

​Error Codes

​Billing

​Latency and polling

​Related

​MCP integration

Endpoints

Authentication

Request Body

Parameters

Generation modes and image order

Writing reference notes

Targets with expression guidance

Image language selection and preservation

Video language selection and preservation

Example

Response

Status Response Fields

Error Codes

Billing

Latency and polling

Related

MCP integration