> ## 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.

# Message Iris

> Ask Iris to change an edit she made, in plain words

# Message Iris

Send Iris one change to an edit she made, in plain words, as you would type it in her chat in Submagic: b-roll, music, sound effects, voice volume, captions and their style, cuts and pauses, framing, the hook title and graphics, eye contact, clean audio, translation.

Iris works in the background. This call returns a `jobId` at once; read the job with [Get Iris Job](https://docs.submagic.co/api-reference/iris-job.md) until its `status` is no longer `running`. A change saves a new version of the edit, and the versions before it are kept.

> [!NOTE]
>
> This endpoint requires authentication and has a rate limit of 500 requests per
> hour. Messages to Iris do not use credits.

## Limits

* Iris only changes projects she edited: ones made with [Create Iris Project](https://docs.submagic.co/api-reference/iris-create-project.md) or an Iris template in the Submagic app. Their `aiEditTemplate` in [Get Project](https://docs.submagic.co/api-reference/get-project.md) starts with `ref:`.
* The edit must be finished: wait until the project's `status` is `completed`.
* Iris needs a paid plan.
* Iris works on one message at a time. A message sent while she is still working is refused with `409` and the `jobId` to wait for.
* Each video allows a limited number of messages, the same as in the app, and an account can send up to 30 messages an hour. Send everything you want changed in one message rather than one message per change.
* The messages show in the project's chat in Submagic.

## Authentication

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

Your Submagic API key starting with `sk-`

## Path Parameters

**id** `string` *required*

The unique identifier (UUID) of the project Iris edited

## Request Body

**message** `string` *required*

What to change, in your words (1-4000 characters), e.g. "make the music
quieter" or "add a b-roll of a city at night when I mention New York"

## Response

**jobId** `string`

The message's job ID. Read it with [Get Iris Job](https://docs.submagic.co/api-reference/iris-job.md).

**projectId** `string`

The project's ID

**fromVersion** `number`

The version of the edit Iris is changing

**status** `string`

Always `running`

## Error Responses

**error** `string`

Error code: `VALIDATION_ERROR`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`,
`CONFLICT`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_SERVER_ERROR`

**message** `string`

What went wrong, in plain words

**reason** `string`

When Iris refused the message, the refusal's code, e.g. `not_iris`,
`iris_making`, `no_edit`, `iris_paid_plan` or `chat_limit`

**jobId** `string`

On a `409` while Iris works on an earlier message: that message's job, to
wait for

```bash cURL theme={null}
curl -X POST "https://api.submagic.co/v1/projects/11111111-1111-4111-8111-111111111111/iris" \
  -H "x-api-key: sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Make the music quieter"
  }'
```

```javascript JavaScript theme={null}
const messageIris = async (projectId, message) => {
  const response = await fetch(
    `https://api.submagic.co/v1/projects/${projectId}/iris`,
    {
      method: "POST",
      headers: {
        "x-api-key": "sk-your-api-key-here",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ message }),
    }
  );

  return response.json();
};

const { jobId } = await messageIris(
  "11111111-1111-4111-8111-111111111111",
  "Make the music quieter"
);
```

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

def message_iris(project_id, message):
    url = f'https://api.submagic.co/v1/projects/{project_id}/iris'
    headers = {
        'x-api-key': 'sk-your-api-key-here',
        'Content-Type': 'application/json'
    }

    response = requests.post(url, headers=headers, json={'message': message})
    return response.json()

job = message_iris(
    '11111111-1111-4111-8111-111111111111',
    'Make the music quieter'
)
```

```json 202 Accepted theme={null}
{
  "jobId": "22222222-2222-4222-8222-222222222222",
  "projectId": "11111111-1111-4111-8111-111111111111",
  "fromVersion": 2,
  "status": "running"
}
```

```json 400 VALIDATION_ERROR - Not an Iris Project theme={null}
{
  "error": "VALIDATION_ERROR",
  "message": "This project was not edited by Iris. Iris works on projects made with an Iris template in the Submagic app.",
  "reason": "not_iris"
}
```

```json 403 FORBIDDEN - Message Limit theme={null}
{
  "error": "FORBIDDEN",
  "message": "You've used all 20 messages for this video.",
  "reason": "chat_limit"
}
```

```json 404 NOT_FOUND theme={null}
{
  "error": "NOT_FOUND",
  "message": "Project not found",
  "reason": "not_found"
}
```

```json 409 CONFLICT - Still Making the Edit theme={null}
{
  "error": "CONFLICT",
  "message": "Iris is still making this edit. Try again once the project is completed.",
  "reason": "iris_making"
}
```

```json 409 CONFLICT - Still Working theme={null}
{
  "error": "CONFLICT",
  "message": "Iris is still working on your last message.",
  "jobId": "22222222-2222-4222-8222-222222222222"
}
```


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