Via scripts/generate_image.py call Seedream 4.0 to generate professional-grade images.
Acceptance criteria (self-check before each generation task is completed)
- The prompt has been structurally optimized ([subject]+[style]+[details]+[quality words]), not passed through the user's original words directly
- size / aspect_ratio matches the intended use (see the parameter reference table), not run with bare default values
- The image has been saved to disk and theactual file pathreported back to the user
- For important uses (poster/brand), generate ≥3 images to choose from
- Informed the user of this run's consumption (number of images × resolution); for 4K, explained in advance that it takes longer and consumes more quota
What not to do
- Do not edit, redraw, or extend existing images—only do text-to-image (reference images are used only for style guidance)
- When there is no
SEGMIND_API_KEYdo not force an attempt: tell the user to get one at segmind.com, or switch to another image-generation skill in the environment - Do not make conclusions about the copyright ownership of generated content
- When the user just wants a quick throwaway image, do not launch a full requirements questionnaire; use a reasonable default and generate directly
Workflow
1. Gather requirements (ask only for what is missing, do not go through a questionnaire item by item)
Required: image content description. Recommended to confirm: size (default 2K), aspect ratio (default 1:1), quantity (default 1).
Use → parameter reference table
| Use | size | aspect_ratio | max_images |
|---|---|---|---|
| Social media | 2K | 1:1 or 9:16 | 1-3 |
| Web banner | 2K | 16:9 or 21:9 | 1 |
| Print poster | 4K | 4:3 or custom | 1-2 |
| Product image | 2K | 3:2 or 4:3 | 3-5 |
| Concept design | 2K | 16:9 | 5-10 |
2. Optimize the prompt
Structure: [subject] + [style] + [details] + [quality modifiers], add lighting and atmosphere; when text within the image is needed, specify the text content and font style explicitly; 200-300 words is recommended.
Example: "a cat" → "A fluffy orange tabby cat on a wooden windowsill, golden hour lighting, cozy interior, warm palette, professional photography, detailed fur texture".
Style keyword library and more patterns:references/prompt_engineering.md。
3. Execute
python scripts/generate_image.py \
--prompt "优化后的提示词" \
--size 2K --aspect-ratio 16:9 --max-images 1 \
--output-dir ./outputs
# API key 从环境变量 SEGMIND_API_KEY 读取，或用 --api-key 传入
Advanced usage (reference images image_input ≤3 / sequential batch sequential=True keep a series consistent / size=custom custom width and height):
For a Python call example, see references/quick_start.md; for full parameter descriptions, see references/api_reference.md。
4. Iterate
When unsatisfied, first ask specifically what they are unsatisfied with, then adjust accordingly: insufficient detail → add description; wrong style → change style keywords or use reference images; clarity → upgrade to 4K; more options → add more images.
Known pitfalls
| Pitfall | Specific manifestation | Response |
|---|---|---|
| 401 / quota exhausted | API reports a 401 or quota error | Check SEGMIND_API_KEY; inform the user truthfully about quota issues, do not silently retry and burn quota |
| Content moderation rejection | Prompt contains sensitive elements and is rejected | Inform the rejection reason category, rewrite the prompt to circumvent it and retry once; if rejected consecutively, stop and confirm with the user |
| Text in the image is blurry | Generated poster text is blurry or has typos | Specify the text content + font style explicitly in the prompt, add "high contrast, bold typography"; upgrade to 4K; if still not working, switch to "leave space for adding text in post" |
| 4K time expectations | User thinks it is stuck | Explain in advance that 2K takes about 2 seconds, 4K takes about 4-6 seconds, and batches stack linearly |
| Over-limit parameters fail silently | >15 images or >3 reference images | Validate parameter upper limits before generation; if over the limit, split first or ask |
| Pass short prompts through directly | "a cat" sent directly to the API, producing mediocre images | First acceptance criterion: must optimize first |
Reference documents (load on demand)
| File | When to read |
|---|---|
references/prompt_engineering.md |
When optimizing prompts or looking up the style keyword library |
references/api_reference.md |
When complete parameter descriptions, error codes, and performance metrics are needed |
references/quick_start.md |
When Python call examples are needed (reference images/batch/custom sizes) |
evals/routing-evals.json — trigger boundary regression test cases, after changing description use the repository root scripts/run_routing_evals.py to validate.