> ## Documentation Index
> Fetch the complete documentation index at: https://docs.submagic.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Iris Project

> Have Iris edit a video from a link in one of her templates

# Create Iris Project

Have Iris, Submagic's editing assistant, edit a video from a link. From a talking video of up to 3 minutes, she makes a finished short-form edit in the template you pick: cuts, captions, b-roll from stock, music, sound effects and graphics. She edits your own footage; she does not make AI-generated video.

The project is made as it is when you upload to Iris in the Submagic app, with the same checks. The edit takes a few minutes.

> [!NOTE]
>
> This endpoint requires authentication and has a rate limit of 500 requests per
> hour. The same `videoUrl` can be sent at most 10 times a minute.

> [!WARNING]
>
> An Iris edit is charged as in the Submagic app, from your account's credits,
> never from API credits (see [Credits](https://docs.submagic.co/mcp-server.md#credits)). Each call starts
> and charges a new edit, so do not retry a call that succeeded. A request that
> is refused, or a project that fails, is not charged.

## Requirements

* A paid plan, or the one free Iris edit a free account has
* A video of up to 3 minutes. A longer one is not refused by this call: the project fails, with the reason in `failureReason`
* One Iris edit starting at a time per account

## Authentication

**x-api-key** `string` *required*

Your Submagic API key starting with `sk-`

## Request Body

**videoUrl** `string` *required*

A direct link to the video file, or a public Google Drive or Dropbox link

**template** `string` *required*

The Iris template to edit in: an `id` from [Iris
Templates](https://docs.submagic.co/api-reference/iris-templates.md), e.g. `ref:paprika-ref`

**title** `string`

Project title (1-100 characters). Defaults to the video's file name, or
"Untitled video" when the link has none.

**language** `string`

The video's spoken language, as a language code (e.g. `en`). Defaults to your
account's language preference, else it is detected. See
[Languages](https://docs.submagic.co/api-reference/languages.md).

**ratio** `string`

The edit's frame: `9:16`, `4:5`, `1:1` or `16:9`. Defaults to `9:16`.

**cut** `boolean`

Cut pauses and bad takes. Defaults to `true`.

**broll** `boolean`

Add b-roll. Defaults to `true`.

**music** `boolean`

Add music. Defaults to `true`.

**cutout** `boolean`

Put text behind the speaker, on templates that do it. Costs more credits.
Defaults to `false`.

**brandKitId** `string`

The ID (UUID) of one of your brand kits to apply. See [List Brand
Kits](https://docs.submagic.co/api-reference/list-brand-kits.md).

**webhookUrl** `string`

A URL Submagic calls with a `POST` once Iris has made the edit, or could not.
See [Webhook](#webhook) below.

## Response

**id** `string`

The new project's ID (UUID format)

**uploadId** `string`

ID of the video download

**title** `string`

The project's title

**template** `string`

The Iris template the project uses, e.g. `ref:paprika-ref`

**status** `string`

Always `processing`

## Error Responses

**error** `string`

Error code: `VALIDATION_ERROR`, `UNAUTHORIZED`, `INSUFFICIENT_CREDITS`,
`FORBIDDEN`, `NOT_FOUND`, `CONFLICT`, `BAD_REQUEST`, `RATE_LIMIT_EXCEEDED` or
`INTERNAL_SERVER_ERROR`. `INTERNAL_SERVER_ERROR` always comes with a 5xx
status.

**message** `string`

What went wrong, in plain words

**reason** `string`

When Submagic refused the edit, the refusal's code, e.g. `unknown_template`,
`irisPaidPlan` or `irisMonthlyCap`

## Webhook

With a `webhookUrl`, Submagic sends one `POST` with a JSON body when the edit ends:

* `status: "completed"`: Iris made the edit.
* `status: "failed"`: Iris could not make it, or never started (for example, a video over 3 minutes, or one whose speech could not be transcribed). `error` says why. When Iris ran but made no edit, the project itself still completes, with captions only.

```json theme={null}
{
  "projectId": "3f2b8c1e-6d4a-4f0b-9a7e-2c5d8e1f4a6b",
  "status": "completed",
  "title": "talk",
  "previewUrl": "https://app.submagic.co/view/3f2b8c1e-6d4a-4f0b-9a7e-2c5d8e1f4a6b",
  "duration": 42,
  "completedAt": "2026-11-18T10:00:00.000Z"
}
```

The edit has no video file yet: call [Export Project](https://docs.submagic.co/api-reference/export-project.md) to render it. If your endpoint does not answer with a 2xx, Submagic makes up to 3 attempts in all. The same webhook can arrive more than once: use `projectId` to ignore a repeat.

## After creating

1. Wait for the webhook, or call [Get Project](https://docs.submagic.co/api-reference/get-project.md) with the returned `id` until `status` is `completed` or `failed`. A failed project has its reason in `failureReason`.
2. To change the edit, send Iris a message with [Message Iris](https://docs.submagic.co/api-reference/iris-message.md).
3. To get the video file, call [Export Project](https://docs.submagic.co/api-reference/export-project.md), then Get Project until `downloadUrl` is set.

```bash cURL theme={null}
curl -X POST "https://api.submagic.co/v1/iris/projects" \
  -H "x-api-key: sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://cdn.example.com/talk.mp4",
    "template": "ref:paprika-ref",
    "ratio": "9:16",
    "music": false
  }'
```

```javascript JavaScript theme={null}
const createIrisProject = async () => {
  const response = await fetch("https://api.submagic.co/v1/iris/projects", {
    method: "POST",
    headers: {
      "x-api-key": "sk-your-api-key-here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      videoUrl: "https://cdn.example.com/talk.mp4",
      template: "ref:paprika-ref",
      ratio: "9:16",
      music: false,
    }),
  });

  return response.json();
};

const project = await createIrisProject();
console.log("Iris project:", project.id);
```

```python Python theme={null}
import requests

def create_iris_project():
    url = 'https://api.submagic.co/v1/iris/projects'
    headers = {
        'x-api-key': 'sk-your-api-key-here',
        'Content-Type': 'application/json'
    }
    data = {
        'videoUrl': 'https://cdn.example.com/talk.mp4',
        'template': 'ref:paprika-ref',
        'ratio': '9:16',
        'music': False
    }

    response = requests.post(url, headers=headers, json=data)
    return response.json()

project = create_iris_project()
print(f"Iris project: {project['id']}")
```

```json 201 Created theme={null}
{
  "id": "33333333-3333-4333-8333-333333333333",
  "uploadId": "9b2f6c1e-4d3a-4f5b-8e7c-1a2b3c4d5e6f",
  "title": "talk",
  "template": "ref:paprika-ref",
  "status": "processing"
}
```

```json 400 VALIDATION_ERROR - Unknown Template theme={null}
{
  "error": "VALIDATION_ERROR",
  "message": "Unknown Iris template. List the ones this account can use with GET /v1/iris/templates.",
  "reason": "unknown_template"
}
```

```json 400 VALIDATION_ERROR - Invalid Ratio theme={null}
{
  "error": "VALIDATION_ERROR",
  "message": "ratio invalid value '3:4'. Expected one of: 9:16, 4:5, 1:1, 16:9"
}
```

```json 403 FORBIDDEN - Monthly Limit theme={null}
{
  "error": "FORBIDDEN",
  "message": "You have made 20 Iris edits this month. Write to us to get more.",
  "reason": "irisMonthlyCap"
}
```

```json 409 CONFLICT - Another Edit Starting theme={null}
{
  "error": "CONFLICT",
  "message": "Another Iris edit is starting on this account. Try again in a few seconds.",
  "reason": "iris_starting"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.