# creator_video

> Make a video of a creator saying a script

`POST /api/v2/creator_video`

A talking video from a creator in GET /creators. Gated preview. Needs the `generate` scope.

- Auth: API key (Authorization: Bearer)
- Key scope needed: `generate`
- Raw spec: https://app.diffusr.ai/api/v2/openapi.json

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | no | 1-255 visible ASCII characters you make up for this request (a UUID is fine). Send the same key to retry safely: you get the first job back instead of paying twice. Reusing a key for a different request answers 409 IDEMPOTENCY_CONFLICT. Wins over `idempotency_key` in the body. |

## Request body (JSON)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `creator_id` | string | yes | From list_creators. |
| `script` | string | yes | What the creator says to camera, word for word. Length of the video follows the script. |
| `resolution` | "480p" \| "720p" | no |  |
| `dry_run` | boolean | no | true = only check the request and return the price in credits. Nothing is made, nothing is spent. |
| `idempotency_key` | string | no | A unique string you make up for this request. Retry with the same key and you get the first result back instead of paying again. |
| `callback_url` | string | no | Optional. A public https:// link. When the job finishes (done, failed or canceled) we POST the finished result here, signed. See the docs for checking the signature. Polling get_result still works. |

## Example

**cURL**

```bash
curl -X POST https://app.diffusr.ai/api/v2/creator_video \
  -H "Authorization: Bearer $DIFFUSR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "creator_id": "CREATOR_ID_FROM_LIST_CREATORS",
  "script": "I tried this for a week and I am not going back."
}'
```

**TypeScript**

```ts
import { Diffusr } from "diffusr";

const d = new Diffusr(); // reads DIFFUSR_KEY
const job = await d.creatorVideo({
  creator_id: "CREATOR_ID_FROM_LIST_CREATORS",
  script: "I tried this for a week and I am not going back.",
});
const result = await d.waitFor(job.id);
console.log(result.output?.url);
```

**Python**

```python
from diffusr import Diffusr

d = Diffusr()  # reads DIFFUSR_KEY
job = d.creator_video(
    creator_id="CREATOR_ID_FROM_LIST_CREATORS",
    script="I tried this for a week and I am not going back.",
)
result = d.wait_for(job["id"])
print(result["output"]["url"])
```

Same call as a dry run (the price, nothing made, nothing spent):

**cURL**

```bash
curl -X POST https://app.diffusr.ai/api/v2/creator_video \
  -H "Authorization: Bearer $DIFFUSR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "creator_id": "CREATOR_ID_FROM_LIST_CREATORS",
  "script": "I tried this for a week and I am not going back.",
  "dry_run": true
}'
```

**TypeScript**

```ts
import { Diffusr } from "diffusr";

const d = new Diffusr(); // reads DIFFUSR_KEY
const job = await d.creatorVideo({
  creator_id: "CREATOR_ID_FROM_LIST_CREATORS",
  script: "I tried this for a week and I am not going back.",
  dry_run: true,
});
console.log(job); // the price, nothing was made
```

**Python**

```python
from diffusr import Diffusr

d = Diffusr()  # reads DIFFUSR_KEY
job = d.creator_video(
    creator_id="CREATOR_ID_FROM_LIST_CREATORS",
    script="I tried this for a week and I am not going back.",
    dry_run=True,
)
print(job)  # the price, nothing was made
```

## Response

### 200 ApiDryRun

dry_run was true: the price, nothing made, nothing spent.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `dry_run` | true | yes |  |
| `test` | true | no | true when a test key made the call: the price is real, nothing real ran. Absent for live keys. |
| `credits_estimated` | number | yes |  |
| `price` | object | no |  |
| `price.credits` | number | yes | The most this call costs, in whole credits (1 credit = $0.01). |
| `price.usd` | string | yes | The same price in US dollars, e.g. "0.0336". |
| `price.tariff` | "direct" \| "outcome" | yes | "direct" = your prompt goes to the model as sent; "outcome" = a result we shape (Recast, creator video). |
| `price.tariff_version` | string | yes |  |
| `price.expires_at` | string | yes | The quoted price holds until then (ISO time). |
| `duration_sec` | number | no |  |
| `warnings` | string[] | no |  |
| `note` | string | yes |  |

### 202 ApiStarted

The job started. Poll GET /results/{id}.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The job id. Poll GET /results/{id} with it, or wait for the callback. |
| `status` | string | yes | "PENDING" on a new start; the run's current status when a retried Idempotency-Key replays the first job. |
| `credits_estimated` | number | yes | The most this job can cost, in credits. |
| `idempotent_replay` | true | no | true when this is the FIRST job again, answering a retried Idempotency-Key. |
| `test` | true | no | true when a test key made the call: the price is real, nothing real ran. Absent for live keys. |
| `price` | object | no | The price, locked in at start. |
| `price.credits` | number | yes | The most this call costs, in whole credits (1 credit = $0.01). |
| `price.usd` | string | yes | The same price in US dollars, e.g. "0.0336". |
| `price.tariff` | "direct" \| "outcome" | yes | "direct" = your prompt goes to the model as sent; "outcome" = a result we shape (Recast, creator video). |
| `price.tariff_version` | string | yes |  |
| `price.expires_at` | string | yes | The quoted price holds until then (ISO time). |
| `duration_sec` | number | no |  |
| `warnings` | string[] | no | Heads-ups that did not stop the call. |
| `next` | string | yes | What to do next, in words. |

## Errors

Every error body is `{ error, code, request_id, ... }`. See https://diffusr.ai/docs/errors.

- 401: Missing, wrong, revoked or expired API key (code UNAUTHORIZED, KEY_REVOKED, KEY_EXPIRED).
- 402: Not enough credits, or an API budget would be passed (INSUFFICIENT_CREDITS, BUDGET_EXCEEDED).
- 403: The key may not do this (SCOPE_DENIED, MODEL_NOT_ALLOWED, TEST_MODE_UNSUPPORTED, ACCOUNT_BLOCKED, allowance_exceeded).
- 409: IDEMPOTENCY_CONFLICT or CALLBACK_NOT_RETRYABLE.
- 413: The request or file is too large (TOO_LARGE, REFERENCE_TOO_LARGE).
- 422: The request is not valid (VALIDATION_FAILED, INVALID_JSON, PREFLIGHT_FAILED, CALLBACK_URL_INVALID, REFERENCE_*). `issues` lists each problem. Nothing was charged.
- 429: Too many requests or jobs (RATE_LIMITED, CONCURRENCY_LIMIT, UPLOAD_QUOTA, …). Wait Retry-After seconds, then retry.
- 500: Our fault (INTERNAL_ERROR). Quote request_id to support.
- 503: Paused or busy (API_PAUSED, MODEL_PAUSED, PROVIDER_PAUSED, PROVIDER_BUSY, UNAVAILABLE). Wait Retry-After seconds, then retry.

## Charges

Costs credits (1 credit = $0.01). Send `dry_run: true` first: it answers with the price and spends nothing. You are charged when the result is delivered and never more than the quoted price. Work that fails, is canceled before it runs, or is never delivered is not charged. A test key quotes the same price and charges nothing. It is priced at the outcome rate: a result we shape for you, so the rate is higher than the model prices on the Prices page. Use `dry_run: true` for the exact price.