> For the complete documentation index, see [llms.txt](https://docs.avastudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avastudio.com/api-and-mcp/project-agent.md).

# Clone and plan in a project

Use `project_ask` to work with the same content-planning agent you use in Studio's Create flow and project chat. It can clone a TikTok video or photo carousel, adapt a reference for your brand, and plan with your images or videos. Your project and conversation are available in Studio too.

The key or connected app needs **Production** permission and enough credits for the work. No paid Ava plan is required: active [starter credits](https://docs.avastudio.com/api-and-mcp/credits-and-pricing.md#free-accounts-and-starter-credits) can fund planner turns and media generation. Free accounts have video-model and usage limits. Planning still uses AI credits even when `generate` is false.

#### Start a project and clone a reference

Create an empty project with `project_create`, or choose one from `project_list`. Then call:

```json
{
  "project_id": "<project_id>",
  "message": "Clone this carousel for my brand, keeping the slide order and using my product photos. Use my selected actor if a person appears.",
  "attachments": [
    {
      "type": "carousel",
      "source": { "url": "https://www.tiktok.com/@creator/photo/<post_id>" }
    }
  ],
  "generate": true,
  "media_credit_limit": 300,
  "idempotency_key": "clone-carousel-20261015-01"
}
```

For REST, send that JSON to `POST https://mcp.avastudio.com/v1/project_ask`; for MCP, call the `project_ask` tool with those arguments. A video reference uses `type: "url"` and its public TikTok, Instagram or YouTube link. You can also paste a reference link into `message`.

The call returns a job. Poll `jobs_get` until it succeeds or fails. On success, the result contains `reply`, `needs_input`, `plan_ready`, `generated` and `project`.

* `needs_input: true`: relay the planner's question and send the user's answer with another `project_ask` on the **same project**. For example, a carousel showing a person may need a choice between keeping that person and using your actor. Do not invent their answer.
* `plan_ready: true`: the planner has saved a scene plan. Omit `generate`, or set it to `false`, to stop here for review.
* `generated: true`: the ready plan went through Studio's generation and composition pipeline. Inspect `project.scenes` for individual media results and open `project.studio_url` to review it.

A carousel follows Studio's image clone flow: one scene per source slide. It is not sent through the video-only `draft_clone` workflow.

#### Give the planner media

Attach up to ten images, videos or reference links per turn:

```json
{
  "project_id": "<project_id>",
  "message": "Use this product photo and demo clip when adapting the reference.",
  "attachments": [
    { "type": "image", "source": { "library_asset_id": "<photo_asset_id>" } },
    { "type": "video", "source": { "library_asset_id": "<video_asset_id>" } }
  ],
  "media_credit_limit": 500
}
```

Use `library_list` to find saved assets. For ChatGPT attachments, call `library_add { files: [...] }` with the native file objects (required `download_url` and `file_id`, optional `mime_type` and `file_name`), poll `jobs_get`, then pass the returned `library_asset_id` in the project attachment. Ava copies the bytes directly. Other clients can upload local bytes with `library_upload_url`, then save them with `library_add`. A public HTTPS image or video can also use `source: { "url": "..." }`; Ava imports it safely. Brand media can use `source: { "media_id": "..." }`.

An upload URL alone does not transfer a file. ChatGPT uses the native `files` input on `library_add`; other clients without file transfer support need a public link or a Studio upload. If a temporary attachment link expires, reattach the file.

When the user approves generation after reviewing a plan, continue with `project_ask` on the same project and set `generate: true`. Poll the job, inspect the saved project and export the finished video. A plan or a list of prompts is not a generated video.

#### SDK and CLI

See [SDK setup](https://docs.avastudio.com/api-and-mcp/sdk.md) or [CLI setup](https://docs.avastudio.com/api-and-mcp/cli.md) first. Basic project-agent calls require client version 0.1.1 or newer; history and watermark options require 0.1.2. Native ChatGPT attachment schemas and metadata require 0.1.3.

```typescript
const result = await client.runJob("project_ask", {
  project_id: "<project_id>",
  message: "Clone this TikTok video: <url>",
  generate: true,
  media_credit_limit: 1000,
});
console.log(result.reply, result.project.studio_url);
```

```bash
avastudio project ask <project_id> \
  --message "Clone this TikTok video: <url>" \
  --generate --media-credit-limit 1000 --wait
```

#### Credits and retries

Each turn starts with **50 API credits** and charges **10 plus its metered AI usage**, returning the unused hold. Any media preparation or generation costs Studio's normal media credits, held separately before the provider runs.

`media_credit_limit` bounds the **estimated media work admitted by this turn**, including voiceovers and reference images prepared while planning. The default is 300 credits; use 0 to plan without paid media preparation. A key with a monthly budget counts that allowance up front, and successful turns reconcile it to actual spend. Provider prices can differ from estimates. After a partial failure, completed media remains charged and uncertain media work retains its estimated budget reservation.

Leave enough monthly budget for both holds: 50 API credits plus the media allowance (300 by default). A larger 1,000-credit media allowance initially needs 1,050 credits of remaining monthly budget. Increase the key or connected app's budget before requesting that work.

Reuse the same idempotency key to retry the same action. Send a new key for a follow-up answer or a different instruction. Studio and the API share the project conversation; wait for a running turn to finish before starting another one.

Use `project_get` to inspect the project and `export_render` to export a completed video.

#### Choose the right tool

| Goal                                                               | Tool           |
| ------------------------------------------------------------------ | -------------- |
| Clone or plan directly inside a project, with references and media | `project_ask`  |
| Draft a written brief from a video reference                       | `draft_clone`  |
| Research and plan a campaign                                       | `plan_run`     |
| Talk to the campaign copilot                                       | `ava_ask`      |
| Adjust an existing video's timeline                                | `project_edit` |

See [Credits and pricing](https://docs.avastudio.com/api-and-mcp/credits-and-pricing.md), [Jobs, retries and errors](https://docs.avastudio.com/api-and-mcp/jobs-retries-and-errors.md) and the [Studio tool reference](https://docs.avastudio.com/api-and-mcp/tools/studio.md).

#### Conversation history and turn outcomes

Use `project_history { project_id, limit: 30 }` to read saved user and assistant messages and reference attachments. Messages arrive newest first; pass `next_cursor` as `cursor` to fetch older pages. Tool-only pages can be empty and still have a cursor. This read is free and requires ownership of the project and `campaigns:read`; internal prompts and tool traces are excluded.

`project_ask` results now report `outcome`: `completed`, `awaiting_input`, `blocked`, or `partial`. Only `awaiting_input` sets `needs_input: true` and supplies the actual `question`. A blocked turn fails its job and retains its result, project and saved work; inspect `jobs_get`, `project_get` and history before continuing. Partial results remain deliverable and include `advisories`; fix timeline issues without regenerating successful scenes. AI/media already used is still charged, with the unused reservation released.

The SDK's `runJob` throws `AvaApiError` for a failed job and retains the final job as `error.job`, including `job_id` and any partial `result`. Use that saved state to continue instead of starting the same paid operation again. `waitForJob` returns failed jobs directly for callers that prefer to inspect the status themselves.

Generated replies describe the result after composition. Caption ingredients alone are not timeline text: inspect `project_get` to verify placement. Source-declared editorial overlays are materialized from their saved timing and geometry; missing placements are returned as advisories.

`export_render` accepts `watermark: "auto" | "required" | "none"`. Auto follows the project owner's entitlement, required includes a watermark, and none requires a paid owner. Cached exports are reused only with the same watermark setting.

Use `research_search { query, media_type: "carousel" }` for photo references, or `video` / `all`. Photo posts expose `is_photo_post: true` and `/photo/` links.

The SDK/CLI already retry transient connection failures with bounded backoff and reuse the same operation id for paid calls. Other MCP clients may safely retry reads such as `project_get` after a connection reset; inspect the original job before repeating a paid operation.
