--- title: "Generate Magic Prompt" method: POST path: "/magic-prompt" tags: ["prompt"] --- # Generate Magic Prompt `POST /magic-prompt` Transforms basic prompts into a magic prompt. Internal use only (feature flagged). TODO: update description if enabled externally. ## Request body - MagicPromptRequest — A request to generate a magic prompt - `prompt` string — The prompt to enhance with a magic prompt. Mutually exclusive with `messages`; one of the two must be set. - `magic_prompt_version` 'V_0' | 'V_0_1' | 'V_0_2' | 'V_0_3' | 'V_0_4' | 'V_0_5' | 'V_0_6' | 'V_0_7' | 'V_0_8' | 'V4_QWEN_3_5_27B' | 'V4_QWEN_3_5_27B_PREFUSED' | 'V4_QWEN_3_5_27B_FULL_FINETUNE' | 'V4_QWEN_3_5_27B_FULL_FINETUNE_LORA' | 'V4_QWEN_3_5_27B_EXPERIMENTAL' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_Q36_2P5K' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_NONNAS_2P5K' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_NONNAS_5K' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_ALTCAP_BAL_9K' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_ALTCAP_BAL_10K' | 'V4_QWEN_3_5_27B_SGLANG_EXPERIMENTAL_Q36_2P5K' | 'V4_QWEN_3_5_27B_SGLANG_EXPERIMENTAL_Q36_2P5K_TP2' | 'V4_QWEN_3_5_27B_PRUNA_FP8' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_01' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_02' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_03' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_04' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_05' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_06' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_07' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_08' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_09' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_10', required — The magic prompt version to use when magic prompt option is set to AUTO or ON. - `classify_prompt_category` boolean, required — Whether to classify the prompt into a use case category. - `style_type` 'AUTO' | 'GENERAL' | 'REALISTIC' | 'DESIGN' | 'CUSTOM' | 'FICTION' | 'STYLIZED' — The style type to generate with. - `seed` integer — Random seed for reproducible generation - `character_reference_images` string[] — Generations with character reference are subject to the character reference pricing. A set of images to use as character references (maximum total size 10MB across all character references), currently only supports 1 character reference image. The images should be in JPEG, PNG or WebP format. - `system_prompt` string — A system prompt to use for the magic prompt. - `aspect_ratio` '1x3' | '3x1' | '1x2' | '2x1' | '9x16' | '16x9' | '10x16' | '16x10' | '2x3' | '3x2' | '3x4' | '4x3' | '4x5' | '5x4' | '1x1' — The aspect ratio to use for image generation, which determines the image's resolution. Cannot be used in conjunction with resolution. Defaults to 1x1. - `temperature` number, float — Sampling temperature override. Defaults to the trainer-conditioned value when omitted (0.7 for V4_QWEN_3_5_27B). Only honored with V4 magic-prompt versions; supplying it with another version returns 400. - `top_p` number, float — Nucleus-sampling top_p override. Only honored with V4 versions. - `top_k` integer — Top-k sampling override. Only honored with V4 versions. - `min_p` number, float — min_p sampling override. Only honored with V4 versions. - `max_tokens` integer — Cap on the number of tokens the model may generate. Defaults to 4096 (the trainer's reference cap) when omitted. Only honored with V4 versions. - `presence_penalty` number, float — Presence-penalty override. Only honored with V4 versions. - `frequency_penalty` number, float — Frequency-penalty override. Only honored with V4 versions. - `repetition_penalty` number, float — Repetition-penalty override. Only honored with V4 versions. - `checkpoint` string — Optional override of the LoRA adapter the V4 magic-prompt wrapper downloads and runs. Pass a `gs://` URI pointing at a checkpoint directory containing `adapter_config.json`. When omitted, the wrapper-preloaded production checkpoint is used. Honored with the wrapper-routed LoRA versions `V4_QWEN_3_5_27B` and `V4_QWEN_3_5_27B_FULL_FINETUNE_LORA`; supplying it with `V4_QWEN_3_5_27B_PREFUSED` or `V4_QWEN_3_5_27B_FULL_FINETUNE` (which serve fixed weights and cannot swap adapters per request) or any other version returns 400. - `messages` MagicPromptRequestMessagesInner[] — Pre-formed chat messages forwarded verbatim to V4. Mutually exclusive with `prompt`; exactly one must be set. V4 only. - `role` 'system' | 'user' | 'assistant', required - `content` string, required ## Response `200` Magic prompt generated successfully. - MagicPromptResponse — The response containing generated magic prompt - `magic_prompt` string, required — The generated magic prompt - `magic_prompt_version` 'V_0' | 'V_0_1' | 'V_0_2' | 'V_0_3' | 'V_0_4' | 'V_0_5' | 'V_0_6' | 'V_0_7' | 'V_0_8' | 'V4_QWEN_3_5_27B' | 'V4_QWEN_3_5_27B_PREFUSED' | 'V4_QWEN_3_5_27B_FULL_FINETUNE' | 'V4_QWEN_3_5_27B_FULL_FINETUNE_LORA' | 'V4_QWEN_3_5_27B_EXPERIMENTAL' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_Q36_2P5K' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_NONNAS_2P5K' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_NONNAS_5K' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_ALTCAP_BAL_9K' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_ALTCAP_BAL_10K' | 'V4_QWEN_3_5_27B_SGLANG_EXPERIMENTAL_Q36_2P5K' | 'V4_QWEN_3_5_27B_SGLANG_EXPERIMENTAL_Q36_2P5K_TP2' | 'V4_QWEN_3_5_27B_PRUNA_FP8' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_01' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_02' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_03' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_04' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_05' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_06' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_07' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_08' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_09' | 'V4_QWEN_3_5_27B_EXPERIMENTAL_SLOT_10' — The magic prompt version to use when magic prompt option is set to AUTO or ON. - `served_model_name` string, nullable — Identifier of the underlying model that produced this prompt. For experimental versions, whose backing model can change over time, this reports the model that actually served the request. Null when not applicable. ## Other responses - `400` — Invalid input provided. - `401` — Not authorized to generate magic prompts. - `429` — Too many requests. - `500` — Internal server error. --- [API](https://skmtc.net/ideogram/apis/ideogram-openapi-3-0.md) · [All operations](https://skmtc.net/ideogram/apis/ideogram-openapi-3-0/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ideogram/ideogram-openapi-3-0/revisions/bd40f367a834/schema)