Film Image Gen

Generate film and TV visual content (concept art, posters, storyboards, character designs) via YouChuang AIGC API (api.lk888.ai). Use this skill whenever a user asks you to create images, design visuals, or produce art for film/TV projects.

intent

you're generating visual assets for film/TV work. this skill submits image generation tasks to the YouChuang AIGC API, handles both synchronous direct returns and asynchronous polling workflows, and returns high-quality images with cost tracking. trigger it when the user requests concept art, character designs, posters, storyboards, mood boards, or any visual content for production.

inputs

API Connection (YouChuang AIGC)

• Base URL: https://api.lk888.ai
• Primary API Key: store in env var YOUCHUANG_API_KEY_PRIMARY (format: sk-...)
• Fallback API Key: store in env var YOUCHUANG_API_KEY_SECONDARY (format: sk-...)
• Authentication: Bearer token in Authorization header; fallback to x-api-key header if 401 returned
• Rate limits: depends on subscription tier; expect 429 responses if exceeded

User Inputs

• Prompt text: detailed description of desired image (Chinese or English; English more stable for OpenAI models)
• Model selection: one of gpt-image-2, gpt-image-2-guan, gemini-3-pro-image-preview, gemini-3.1-flash-image-preview, mj_imagine, or grok-4.1-image
• Reference images (optional): 1-14 URLs depending on model
• Dimensions/aspect ratio: user preference or inferred from use case
• Quality/style parameters: quality level, stylization, chaos (model-dependent)

Context / External State

• Current time: needed for timeout calculation (10 minute max poll window)
• Network availability: requests may timeout or 5xx if api.lk888.ai is down
• Task state: track task_id in memory or persistent store if polling spans multiple invocations

procedure

1. Parse user request. Extract intent (which type of visual content), desired dimensions (portrait, landscape, square), style direction (photorealistic, concept art, anime, etc.), and any reference images or mood boards. If ambiguous, ask clarifying questions (e.g., "16:9 or 1:1?" / "quick preview or max quality?").

2. Select best model. Match scenario to model recommendation table: character design → gpt-image-2 with 1024x1536 portrait; scene/environment → gemini-3-pro with 16:9 and 2K; storyboard → gemini-3.1-flash with 16:9 and 1K (fast); film poster → gemini-3-pro with 2:3 and 4K; mood board → gemini-3-pro with 21:9 and 2K; concept art/illustration → mj_imagine with 16:9 and quality 1 and stylize 250. If user specifies a model, use that.

3. Build prompt. Structure using template: [subject description] + [material/costume detail] + [scene environment] + [lighting mood] + [camera angle/shot type] + [art style/director reference] + "cinematic lighting, 8k resolution, concept art". If image contains text, use gemini-3-pro and wrap text in quotes. Chinese prompts work well; English is safer for OpenAI. Be specific; avoid vague words.

4. Assemble request payload. Create JSON object with model name, params object containing prompt (required), images array (optional, with reference URLs), size or aspectRatio, imageSize, quality, and any model-specific fields (botType, stylize, chaos, thinkingLevel, web_search for Gemini models). For gpt-image-2 and gpt-image-2-guan, default size to "auto" unless user specifies. For gemini models, default aspectRatio to "1:1" and imageSize to "2K" unless user specifies.

5. Submit task via POST /v1/media/generate. Send request with Authorization Bearer header (or x-api-key if Bearer fails). If 401 Unauthorized on primary key, retry with secondary key. If 429 Too Many Requests, wait 30 seconds and retry up to 2 times. If 5xx or network timeout, inform user that the API is temporarily unavailable and suggest trying again in 1-2 minutes.

6. Evaluate response type. Check response for two patterns: (A) if data.url or data[0].url exists, extraction synchronous result immediately; go to step 8. (B) if data.task_id exists, note the task_id and proceed to step 7 (async polling). If response is unexpected (missing both), return error to user with raw response for debugging.

7. Poll async task status. Call GET /v1/media/status?task_id={task_id} every 3-5 seconds. On each poll, check is_final field: if true, task has reached terminal state; if false, wait and retry. Also check state field: if "success", extract result_url; if "failed", report error from error field and note that the user has been auto-refunded. Stop polling if is_final === true OR elapsed time exceeds 10 minutes (report timeout). Ignore status and status_group fields (Chinese display only; don't use for logic).

8. Return result to user. Provide image URL (from result_url or direct url), report generation cost (from cost field if available), and note estimated time taken. Optionally offer follow-up options (variations, re-prompt, scale up/down).

decision points

• Model selection: if user requests text-heavy design (poster, logo, type-based art), use gemini-3-pro-image-preview for best text rendering. else if user wants fastest output with wide aspect ratios, use gemini-3.1-flash-image-preview. else if user asks for hyper-realistic/product or commercial look, use gpt-image-2 or gpt-image-2-guan (latter for strict cost control). else if user wants high-end concept art or painterly style, use mj_imagine.

• Synchronous vs. asynchronous: if API response body contains data.url or data[0].url, response is synchronous; skip polling and jump to step 8. else if response contains data.task_id, enter async polling loop (step 7).

• API key fallback: if initial request returns 401 Unauthorized, automatically retry with secondary API key from YOUCHUANG_API_KEY_SECONDARY. if secondary also fails, return error and advise user to check API key validity.

• Rate limit handling: if 429 Too Many Requests, wait 30 seconds and retry. if 429 recurs twice more, halt and inform user that API quota is exhausted; suggest retrying in 1 hour.

• Timeout strategy: if async task polling exceeds 10 minutes of elapsed time without reaching is_final === true, stop polling and offer user the task_id so they can check status manually later. do not loop forever.

• Task failure: if state === 'failed' or error field is non-empty, inform user of error message, confirm refund has been auto-processed, and ask if they want to retry with adjusted prompt or different model.

• Reference images: if user provides reference images, pass URLs in images parameter as array. count and validate: gpt-image-2 allows up to 10 refs; gemini models allow up to 14 refs; mj_imagine allows up to 4 refs; grok-4.1-image allows 1 ref max. if user provides too many, trim to model limit and warn user.

• Empty or null result: if task completes but result_url is null/empty, log as corruption and ask user to retry.

output contract

on success, the skill returns an object containing:

• image_url: string, direct HTTPS URL to generated image file (hosted on YouChuang CDN or partner)
• task_id: string (only if async task); users can store for manual re-check
• generation_cost: number, token cost or credits consumed (from API response cost field)
• elapsed_seconds: number, wall-clock time from submit to final result
• model_used: string, name of model that generated image
• prompt_used: string, final prompt sent to API

optional fields if model supports:

• generation_seed: integer, if model returns reproducibility seed
• usage_tokens: object with input_tokens, output_tokens, total_tokens

image file is PNG or JPEG, min resolution 512x512, max resolution 3840x2160 (varies by model), and hosted at stable URL for at least 30 days.

on error, return object with:

• error: string, human-readable error message
• error_code: string, HTTP status or API error code (e.g., "401_unauthorized", "429_rate_limit", "timeout_10min")
• task_id: string (if async task was created before error; user can retry status check)

outcome signal

user knows the skill worked when: (1) you provide a clickable image URL pointing to a valid visual asset that matches the requested scene/style/dimensions. (2) user can download/view the image and confirm it meets creative brief (correct composition, colors, details, text rendering if applicable). (3) cost and timing feedback is provided so user understands resource usage. (4) if async, polling completed within 10 minutes and image is production-ready. (5) if failure occurred, error message is specific (e.g., "prompt contained policy violation" or "API key expired") and next steps are clear (retry, switch model, provide new reference, update credentials).

Credits: original skill by taosiuman @ clawhub. enriched for Implexa quality standards with explicit decision logic, edge case handling, and async/sync contract clarity. version 2.0.0, YouChuang AIGC API (api.lk888.ai), updated 2026-06-07.