• Base URL:

  https://external-api.arcads.ai

  (or

  ARCADS_BASE_URL

  ).
• Auth: HTTP Basic — use

  ARCADS_API_KEY

  as the username and an empty password unless Arcads documentation for your key specifies otherwise. Example curl:

  curl -u "$ARCADS_API_KEY:" "$ARCADS_BASE_URL/v1/products"

  .
• Never print API keys, commit

  .env

  , or paste keys into

  MASTER_CONTEXT.md

  .

1. Editor-first (default): Ensure

   .env

   exists (copy from

   .env.example

   in the repo root). Ask the user to paste

   ARCADS_API_KEY

   only inside

   .env

   and save. Do not ask them to paste the key in chat unless they insist.
2. Chat-assisted: If they paste the key in chat, write

   .env

   for them, confirm "saved to

   .env

   " without repeating the key, and remind them that chat history may retain secrets—rotate the key in Arcads if the chat could be shared.

.gitignore

.env

1. Repo root

   MASTER_CONTEXT.md

   when present (brand voice, decisions, quirks).
2. This skill's reference.md for routes, bodies, polling.
3. prompting/guide.md then the right

   prompting/prompt-library/

   file for the model (see table below).

• MANDATORY: Before composing any prompt for the API, read the relevant

  prompting/prompt-library/*.md

  file for the chosen model/workflow. Do NOT skip this step — every prompt must align with the vendor guide's formula and best practices.
• Build one clear prompt paragraph; avoid keyword soup.
• For Seedance 2.0 / Sora2 / Veo3.1 / Kling / Grok Video / Nano Banana, align with the official vendor guides linked in each

  prompting/prompt-library/*.md

  file (do not paste full vendor docs into chat—summarize checks).
• Merge slot values from the user and from

  MASTER_CONTEXT.md

  when it conflicts with defaults.

1. Get today's date as

   YYYY-MM-DD

   .

2. GET /v1/products

   → pick the target product (default to whichever

   MASTER_CONTEXT.md

   specifies under "My workspace"). If no default is set: if only one product exists, auto-populate

   MASTER_CONTEXT.md

   with its ID and name; if multiple, ask the user to pick and save their choice to

   MASTER_CONTEXT.md

   .
3. Check existing folders (

   GET /v1/products/{productId}/folders

   ) — if "Arcads API - {today}" already exists, reuse it. Otherwise:

   • POST /v1/folders

     with

     {"productId": "...", "name": "Arcads API - YYYY-MM-DD"}

     .

   • POST /v1/projects

     with

     {"productId": "...", "folderId": "...", "name": "Arcads API - YYYY-MM-DD"}

     .
4. Store the

   projectId

   for the session and pass it in every generation call (

   projectId

   field on Sora2/Veo31/b-roll/scene/image DTOs) and use

   POST /v1/assets/add-to-project

   after generation for asset types that do not accept

   projectId

   directly.

ALWAYS label credit totals as estimates and tell the user to confirm the exact cost in the Arcads platform before generating if precision matters. The Arcads API does not expose billing endpoints; pricing varies by duration, resolution, and reference inputs.

1. logs/arcads-api.jsonl

   — historical record of actual

   creditsCharged

   values for every previous call. Read this first. Grep for entries with the same

   model

   and similar config (same

   duration

   ,

   resolution

   ,

   referenceImagesCount

   ,

   audioEnabled

   ) and use the recorded

   creditsCharged

   as the estimate. This is the most accurate source.

2. MASTER_CONTEXT.md

   → Credit costs — user-provided pricing rules (e.g. "Seedance 2.0 image-to-video ≈ 0.06/sec"). Use when no matching log entry exists.
3. Ask the user — if neither source has data for the config, ask the user and write the answer into

   MASTER_CONTEXT.md

   .

POST /V2/images/generate

• Default:

  "model": "nano-banana-2"

  (Nano Banana 2).
• Optional:

  "model": "nano-banana"

  when the user asks for Nano Banana Pro (the API has no

  nano-banana-pro

  enum — Pro maps to

  nano-banana

  ; see nano-banana.md).

nano-banana-2

model

MASTER_CONTEXT.md

1. Extract the dialogue lines from the full prompt and show them to the user in a dedicated block, separate from the visual/cinematography description.
2. Present them as a clean, numbered list with beat labels (hook / show / demo / verdict, or similar) and any silent beats clearly marked as

   (silent beat — no dialogue)

   .
3. Read the dialogue out loud in your head at a natural pace, time it against the target duration, and flag the total spoken word count plus whether it comfortably fits.
4. Explicitly ask for dialogue approval before moving on — e.g. "Approve this dialogue? (yes / edit / rewrite)". Never assume approval from earlier confirmations (tone, template, credit cost). Dialogue approval is its own gate.
5. Only after the user types

   yes

   (or equivalent) may you proceed to the credit cost confirmation and then generation. If the user says "edit" or proposes changes, revise and re-present the numbered dialogue block until they approve.

📝 Dialogue script (please confirm before I generate)

  1. [HOOK]   "Bro. BRO. Look what just showed up."
  2. [SHOW]   "The PAID SOCIAL stripe? Insane. Like, who greenlit this?"
  3. [DEMO]   (silent beat — thumb brushing the suede, small nod)
  4. [VERDICT] "I'm literally wearing these to the gym tomorrow. You guys have to see these in person."

Total spoken words: ~28  |  Target duration: 15s  |  Fits at natural pace: ✅

Approve this dialogue? (yes / edit / rewrite)

• For Seedance 2.0, Veo 3.1, and Sora 2: embed the dialogue in the

  prompt

  field using a

  Dialogue: "..."

  or

  She speaks: "..."

  pattern (these models generate speech from the text prompt).
• For Seedance 2.0 specifically: before generating, always ask the user whether to enable audio output (

  audioEnabled: true

  ). Also ask whether they want to supply

  referenceAudios

  (e.g. background music or a specific voice clip). Upload audio files via presigned URL if provided.
• For Scene (

  CreateSceneDto

  ): use the dedicated

  script

  field for dialogue and

  prompt

  for visuals.
• For B-roll: no speech — b-roll is silent/ambient by nature. If the user wants speech, redirect to Seedance 2.0, Veo 3.1, Sora 2, or Scene.
• For Nano Banana images: no speech — these are still images. Speech is handled in the subsequent video generation step.

1. Tell the user the script is too long for a single video and show the word/duration math.
2. Offer two options:
   • Split into segments — the agent breaks the script at natural sentence boundaries into chunks that each fit within the model's max duration. Each chunk becomes a separate generation call.
   • Switch models — if they're on Kling (10s max), suggest Sora 2 (up to 20s).
3. If the user chooses to split, generate each segment as a separate video (respecting the generation count — if they asked for 3 variations, generate 3 of each segment).
4. Offer to stitch the final segments together using

   ffmpeg

   :
   • Download all segment videos locally.
   • Concatenate using

     ffmpeg -f concat -safe 0 -i list.txt -c copy output.mp4

     (re-encode if codecs differ).
   • Present the stitched file alongside the individual segments so the user has both.

1. Check dimensions. If the image's longest side is below 1024 px, upscale it using Lanczos resampling so the longest side reaches 1080 px (preserve aspect ratio).
2. Convert to RGB JPEG (quality 90–95) to strip alpha channels and keep payload size reasonable.
3. Re-encode as base64 (for

   refImageAsBase64

   ) or upload the resized file (for

   startFrame

   via presigned URL).

POST /v1/b-roll

422 — The provided image is too small

1. Session folder: Ensure today's dated folder + project exist (see above).
2. Resolve

   productId

   (and

   projectId

   from session folder):

   GET /v1/products

   or ask the user.
3. Ask for script/dialogue: If the output is a video with a person speaking, ask the user for the exact words. Count words to auto-select duration (see "Script length → video duration" above). If too long, offer to split. (Skip for Nano Banana image-only requests.)
   • MANDATORY dialogue confirmation gate (before credit cost / before generation): Extract the dialogue lines from the drafted prompt and present them to the user as a dedicated, numbered block separate from the visual description. Follow the format in Script and dialogue → MANDATORY dialogue confirmation gate. Wait for explicit

     yes

     before moving on. This gate is separate from the credit cost confirmation — both must be satisfied.
4. Nano Banana image model: For

   POST /V2/images/generate

   , confirm Nano Banana 2 (default) vs Nano Banana Pro (

   nano-banana

   ) per the section above. Skip if not an image call.
5. Ask for generation count: Ask how many variations the user wants for this prompt. Default to 1.
6. Show credit cost and get confirmation: Calculate total credits using the cost table above. Present the breakdown to the user. Do NOT proceed until they confirm.
7. Check

   references/

   folder: Before composing the prompt, check the repo-root

   references/

   folder for relevant images:

   references/influencers/

   for person recreation,

   references/products/

   for product showcase,

   references/aesthetics/

   for style/mood. If the user hasn't provided an image but a relevant one exists in

   references/

   , offer to use it. Auto-upscale any reference image if needed. For Veo 3.1, determine whether to use

   startFrame

   or

   referenceImages

   (see section above — default to

   startFrame

   for person photos).
8. Compose JSON per OpenAPI / reference.md. Primary video endpoint:

   POST /v2/videos/generate

   with the appropriate

   model

   value (see

   CreateVideoDto

   in reference.md). Include

   projectId

   when the DTO supports it. Set

   duration

   based on script length for models that require it. For Nano Banana images, use

   POST /v2/images/generate

   with

   model

   set per the Nano Banana section (

   nano-banana-2

   unless the user chose Pro).
   • Seedance 2.0 extras: Set

     resolution

     to

     720p

     (default). Set

     aspectRatio

     to

     9:16

     (UGC/social) or

     16:9

     (landscape). Include

     audioEnabled

     per user confirmation. If the user provided reference images, upload via presigned URL and pass

     filePath

     strings in

     referenceImages

     (max 3). Same for

     referenceVideos

     and

     referenceAudios

     if provided. Keep

     @(img1)

     tokens in the prompt text alongside the

     referenceImages

     array.
   • ⚠️ Seedance 2.0 mutually exclusive input modes (confirmed 2026-04-09):

     referenceVideos

     and

     referenceImages

     cannot be combined in the same request — the API returns

     HTTP 500 UNKNOWN_ERROR

     . Pick one: image-to-video OR video-to-video.

     referenceAudios

     may be combined with either. See

     reference.md

     for details.
   • Seedance 2.0 v2v + human faces — RESOLVED 2026-04-14: v2v with people/faces in reference videos now works. Previously blocked by content checker (April 9). See

     reference.md

     .
   • Seedance 2.0 audio+image 500 regression — RESOLVED 2026-04-14:

     audioEnabled: true

     +

     referenceImages

     now works. Previously returned HTTP 500 (April 9). Always use freshly obtained presigned URLs. See

     reference.md

     .

9. POST

   the correct endpoint N times (once per requested variation) with the same payload. Fire in parallel where possible. Immediately after the POST succeeds, append a log entry to

   logs/arcads-api.jsonl

   with the request config (model, duration, resolution, aspectRatio, audioEnabled, reference counts, promptWordCount, assetId). Do NOT log the full prompt text, API keys, or Authorization headers.
10. Poll:

    GET /v1/videos/{videoId}

    for video IDs;

    GET /v1/assets/{id}

    for asset IDs (including Nano Banana images) until

    status

    is

    generated

    or

    failed

    (see reference.md). Poll all asset IDs concurrently. When polling completes, update the log entry with

    response.status

    ,

    response.creditsCharged

    ,

    response.generationTimeSec

    ,

    response.videoUrl

    ,

    response.thumbnailUrl

    , and

    response.error

    (if failed). See

    logs/README.md

    for the schema.
11. Generated image QA: For each still image produced in this turn (e.g.

    POST /V2/images/generate

    ), follow Generated image QA: inspect the image; if defective, regenerate with a refined prompt until pass or 2 retries are exhausted. Skip this step for video-only outputs with no still to review.
12. Assign ALL assets to session project: After generation (and QA retries), check each asset's

    projects

    array. If it does not include the session

    projectId

    , call

    POST /v1/assets/add-to-project

    . This applies to every generated asset — including failed QA attempts and intermediate assets like Nano Banana stills used as starting frames for subsequent video generations. All assets from the session must end up in the same dated project folder.
13. Present results: Return watch URLs, image URLs, or download URLs for QA-passed stills (or the best attempt after max retries, with a clear note). If multiple variations, present as a numbered list for comparison. Explain

    failed

    with moderation/validation hints if

    422

    occurred. For Nano Banana images used as starting frames, show the image and wait for user approval before proceeding to video generation.

• ALWAYS open the output folder on the user's machine after saving generated files so they can immediately review:

  open "<output_directory>"

  (macOS). Save videos to

  outputs/

  with a descriptive subfolder (e.g.

  outputs/seedance-tests/

  ,

  outputs/clone-ad-tests/

  ).

1. Stitch if split: If the script was split into segments, offer to stitch the final videos together with

   ffmpeg

   and provide both the stitched file and individual segments.

• 401/403: Fix API key / workspace access (setup flow above).
• 404: Wrong UUID; re-fetch lists.
• 422: Validation or moderation — tighten prompt, remove disallowed content, check required enums (aspect ratio, duration).
• 500: Retry later; if repeated, stop and report.

• reference.md — endpoints, auth detail, polling, model mapping notes,

  CreateVideoDto

  schema.
• prompting/guide.md — marketing brief → API.
• Seedance 2.0:
  • prompting/prompt-library/seedance-2.md — main Seedance 2.0 model guide (platform rules, API parameters, style template directory).
  • prompting/prompt-library/seedance-2-ugc.md — 9-layer UGC selfie-style formula for Seedance 2.0.
  • prompting/prompt-library/seedance-2-premium-reveal.md — dark-void premium product reveal (no person).
  • prompting/prompt-library/seedance-2-product-hero.md — elemental product hero with splash/effects (no person).
  • prompting/prompt-library/seedance-2-studio-lookbook.md — studio lookbook with voiceover.
  • prompting/prompt-library/seedance-2-feature-walkthrough.md — fast-paced feature walkthrough demo.
  • prompting/analyze-video/SKILL.md — reverse-engineer a reference video into a reusable Seedance 2.0 prompting template.
  • prompting/clone-ad/SKILL.md — clone a reference video ad for a different product (end-to-end: analyze → adapt → generate).
• Other models:
  • prompting/prompt-library/influencer-recreation.md — analyze a reference photo and recreate the influencer.
  • prompting/prompt-library/ugc-selfie-style.md — cross-model UGC guide (iPhone aesthetic, negative prompts, per-model formulas).
  • prompting/prompt-library/product-showcase.md — product-in-hand video workflow (Nano Banana image → approve → video).
  • prompting/prompt-library/nano-banana.md — Nano Banana image prompting guide.
  • prompting/prompt-library/character-sheet.md — generate a 10-image character sheet for a new AI influencer from a text description.
  • prompting/prompt-library/ugc-product-selfie.md — UGC selfie-style still image: character + product + style references.
• prompting/brand-voice-starter.md — template to copy into

  MASTER_CONTEXT.md

  .