> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hooked.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Character
> Change a character's name, descriptions, style or photo
## Overview
Changes one of your team's characters, the same fields as the character editor in **Studio → Characters**: `name`, `description`, `voiceProfile`, `presetId` and the photo. Send only what changes; fields you leave out keep their value. `description: null` and `voiceProfile: null` clear them.
The photo works as in [Create Character](/api-reference/character/create): `mediaId` (a `COMPLETED` image of your library), `imageUrl` (imported after the response) or `generatePortrait: true` (generated from the description, charged one image), at most one of them. `mediaId: null` removes the photo. With `imageUrl` or `generatePortrait` the answer is `202`; poll [Get Character](/api-reference/character/details) until `imageStatus` is `COMPLETED` or `FAILED`.
A portrait uses the character's description and style after the update, so you can send a new `description` and `generatePortrait: true` together.
```bash cURL theme={null}
curl -X PATCH "https://api.hooked.so/v1/character/cm4xa1b2c0001cd34ef56gh78" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{ "name": "Mia Torres" }'
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.hooked.so/v1/character/cm4xa1b2c0001cd34ef56gh78", {
method: "PATCH",
headers: { "x-api-key": process.env.HOOKED_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({ name: "Mia Torres" }),
});
const { data: character } = await response.json();
```
```python Python theme={null}
import os
import requests
response = requests.patch(
"https://api.hooked.so/v1/character/cm4xa1b2c0001cd34ef56gh78",
headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
json={"name": "Mia Torres"},
)
character = response.json()["data"]
```
```json 200 theme={null}
{
"success": true,
"message": "Character updated",
"data": {
"id": "cm4xa1b2c0001cd34ef56gh78",
"name": "Mia Torres",
"description": "Late 20s, red curly hair, denim jacket",
"voiceProfile": "Warm, slightly husky, speaks fast",
"presetId": "cinematic",
"imageUrl": "https://files.hooked.so/team/public/mia--fid--1a2b.png",
"imageStatus": "COMPLETED",
"createdAt": "2026-09-30T18:00:00.000Z",
"creditsCharged": 0
}
}
```
```json 409 theme={null}
{
"success": false,
"message": "The character's photo is still processing; try again when imageStatus is not PROCESSING"
}
```
## Errors
| Status | Message | Cause |
| - | - | - |
| 400 | `Nothing to update: …` | The body has none of the fields above. |
| 400 | `field: reason` | The same checks as [Create Character](/api-reference/character/create#errors). |
| 401 | `code: "not_authenticated"` | Missing or invalid `x-api-key`. |
| 402 | `missing_credentials`, `subscription_required` or `INSUFFICIENT_CREDITS` | Only with `generatePortrait`. Nothing was changed. |
| 403 | `code: "entitlement_required"` | Your team does not have the Hooked app product. |
| 404 | `Character not found` | No such character in your team (another team's or a malformed id answers the same). |
| 409 | `The character's photo is still processing; …` | A new photo was sent while the current one is still being imported or generated. Nothing was changed. |
## OpenAPI
````yaml PATCH /v1/character/{characterId}
openapi: 3.0.0
info:
title: Hooked API
version: 1.0.0
description: AI Video Generation API
servers:
- url: https://api.hooked.so
security:
- ApiKeyAuth: []
tags:
- name: Videos
description: Create projects, follow them and render videos
- name: Account Analysis
description: Analyze TikTok and YouTube accounts
- name: Channels
description: Connected social accounts you publish to
- name: Publish
description: Schedule videos to your connected accounts
- name: Images
description: 'Image editing: background removal and expansion'
- name: Media
description: 'Your media library: list, import from a URL, upload a file'
- name: Avatars
description: Your team's own avatars (Actors) and their Hook + Demo reactions
paths:
/v1/character/{characterId}:
patch:
tags: []
summary: Update Character
description: >-
Changes what the dashboard's character editor changes: name, visual
description, voice description, style and photo. Fields you leave out
keep their value. A new photo comes from `mediaId`, `imageUrl` or
`generatePortrait` as in Create Character; `mediaId: null` removes it.
Answers 202 when the new photo is still being imported or generated.
operationId: updateCharacter
parameters:
- name: characterId
in: path
required: true
schema:
type: string
description: The character id, from List Characters.
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
maxLength: 60
description: New name.
description:
type: string
nullable: true
maxLength: 2000
description: New visual description; `null` clears it.
voiceProfile:
type: string
nullable: true
maxLength: 500
description: New voice description; `null` clears it.
presetId:
type: string
description: >-
New visual style (`visual-styles` catalog id or your
`custom-`).
mediaId:
type: string
nullable: true
description: >-
A `COMPLETED` image of your library as the new photo; `null`
removes the photo.
imageUrl:
type: string
format: uri
description: >-
A public https JPEG, PNG, WEBP or GIF. It is imported into
your library after the response (free, counted against your
storage); `imageStatus` is `PROCESSING` until then.
generatePortrait:
type: boolean
description: >-
`true` generates a portrait from `description` in the
character's style, after the response. Charged one image at
`imageModel` (4 credits with the default); given back if it
fails.
imageModel:
type: string
description: >-
Image model for `generatePortrait` (an `image-models`
catalog id). Default `gpt_image_2`.
example:
name: Mia Torres
responses:
'200':
description: Character updated
content:
application/json:
schema:
type: object
required:
- success
- data
properties:
success:
type: boolean
message:
type: string
data:
$ref: '#/components/schemas/CharacterWritten'
example:
success: true
message: Character updated
data:
id: cm4xa1b2c0001cd34ef56gh78
name: Mia Torres
description: Late 20s, red curly hair, denim jacket
voiceProfile: Warm, slightly husky, speaks fast
presetId: cinematic
imageUrl: https://files.hooked.so/team/public/mia--fid--1a2b.png
imageStatus: COMPLETED
createdAt: '2026-09-30T18:00:00.000Z'
creditsCharged: 0
'202':
description: Character updated; its new photo is being imported or generated
content:
application/json:
schema:
type: object
required:
- success
- data
properties:
success:
type: boolean
message:
type: string
data:
$ref: '#/components/schemas/CharacterWritten'
example:
success: true
message: Character updated; its photo is processing
data:
id: cm4xa1b2c0001cd34ef56gh78
name: Mia
description: Late 20s, red curly hair, denim jacket
voiceProfile: Warm, slightly husky, speaks fast
presetId: cinematic
imageUrl: null
imageStatus: PROCESSING
createdAt: '2026-09-30T18:00:00.000Z'
creditsCharged: 4
'400':
description: Invalid body, photo or style; nothing was saved or charged
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError400'
example:
success: false
message: >-
mediaId: Pass only one of mediaId, imageUrl or
generatePortrait
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/EntitlementRequired'
'404':
description: >-
No such character in your team (another team's or a malformed id
answers the same)
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound404'
example:
success: false
message: Character not found
'409':
description: >-
A new photo was sent while the current one is still processing, or a
request with the same `Idempotency-Key` is still running. Nothing
was changed.
content:
application/json:
schema:
type: object
required:
- success
- message
properties:
success:
type: boolean
enum:
- false
code:
type: string
message:
type: string
example:
success: false
message: >-
The character's photo is still processing; try again when
imageStatus is not PROCESSING
'422':
$ref: '#/components/responses/IdempotencyMismatch'
'429':
$ref: '#/components/responses/RateLimited429'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
example:
success: false
message: Failed to update the character
security:
- ApiKeyAuth: []
components:
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: >-
Makes the request safe to retry. 1-255 printable ASCII characters, one
per operation (your job id, or a UUID you store), reused on every retry.
Within 24 hours the same key with the same body answers with the first
response and the header `Idempotent-Replayed: true`, without running or
charging again. Keys are scoped to your team and the endpoint. 5xx
answers and refusals before anything ran (401, 402, 403, 409, 429) are
not kept. See [Idempotency](/guides/idempotency).
schema:
type: string
minLength: 1
maxLength: 255
pattern: ^[\x20-\x7E]+$
example: order-1042-video
schemas:
CharacterWritten:
description: The character as saved, and what it cost.
allOf:
- $ref: '#/components/schemas/Character'
- type: object
required:
- creditsCharged
properties:
creditsCharged:
type: number
description: >-
Credits taken for a generated portrait (0 for anything else, and
on BYOK). Given back if the portrait fails.
ValidationError400:
type: object
description: >-
The request is invalid. `message` is `: ` when a field is
to blame.
properties:
success:
type: boolean
enum:
- false
message:
type: string
required:
- success
- message
example:
success: false
message: 'webhook: Must be a valid HTTPS URL'
NotFound404:
type: object
description: >-
Not found. Another team's resource answers the same way as a missing
one.
properties:
success:
type: boolean
enum:
- false
message:
type: string
required:
- success
- message
example:
success: false
message: Project not found
Error500:
type: object
properties:
success:
type: boolean
enum:
- false
message:
type: string
error:
type: string
description: Present on some endpoints
example:
success: false
message: Internal server error
Character:
type: object
description: >-
A Cinematic character of your team (Studio → Characters in the
dashboard). Pass its `id` in `characterIds` of Create Cinematic Video.
required:
- id
- name
- description
- voiceProfile
- presetId
- imageUrl
- imageStatus
- createdAt
properties:
id:
type: string
description: Pass it in `characterIds`.
name:
type: string
description: The character's name, as the story calls it.
description:
type: string
nullable: true
description: The visual description you gave it.
voiceProfile:
type: string
nullable: true
description: How the character sounds, in words. It drives the AI-imagined voice.
presetId:
type: string
nullable: true
description: >-
The visual style its portrait is generated in (a `visual-styles`
catalog id or your `custom-`).
imageUrl:
type: string
nullable: true
description: >-
Its reference photo, as a signed URL that expires. `null` until
`imageStatus` is `COMPLETED`.
imageStatus:
type: string
enum:
- NONE
- PROCESSING
- COMPLETED
- FAILED
description: >-
`NONE`: no photo. `PROCESSING`: a photo imported from `imageUrl` or
a generated portrait is on its way. `COMPLETED`: `imageUrl` is set.
`FAILED`: the import or the portrait failed (a portrait's credits
are given back); set another photo with Update Character.
createdAt:
type: string
format: date-time
Error401:
type: object
description: Missing or invalid `x-api-key`.
properties:
code:
type: string
enum:
- not_authenticated
message:
type: string
example: Not authenticated
errorCode:
type: string
enum:
- NOT_AUTHENTICATED
details:
type: object
additionalProperties:
type: string
example:
code: not_authenticated
message: Not authenticated
errorCode: NOT_AUTHENTICATED
details:
x-api-key: Header not provided or API Key invalid
MissingCredentials402:
type: object
description: >-
BYOK team without the provider keys this request uses. Nothing was
created or charged. Add the keys in Settings → AI keys.
properties:
success:
type: boolean
enum:
- false
description: Present when raised by the spend check
code:
type: string
enum:
- missing_credentials
errorCode:
type: string
enum:
- MISSING_CREDENTIALS
missingProviders:
type: array
items:
type: string
enum:
- openrouter
- elevenlabs
- gemini
- bria
- firecrawl
message:
type: string
details:
type: object
required:
- code
- errorCode
- missingProviders
- message
example:
code: missing_credentials
message: >-
Your team uses its own provider keys (BYOK) and these are missing or
invalid: OpenRouter, ElevenLabs. Add them in Settings → AI keys.
errorCode: MISSING_CREDENTIALS
missingProviders:
- openrouter
- elevenlabs
details: {}
SubscriptionRequired402:
type: object
description: Managed team (generates with Hooked's keys) without a live subscription.
properties:
success:
type: boolean
enum:
- false
code:
type: string
enum:
- subscription_required
errorCode:
type: string
enum:
- SUBSCRIPTION_REQUIRED
message:
type: string
required:
- success
- code
- errorCode
- message
example:
success: false
code: subscription_required
errorCode: SUBSCRIPTION_REQUIRED
message: >-
Your team generates with Hooked's keys, which are paid by your plan.
Subscribe to keep generating.
InsufficientCredits402:
type: object
description: >-
Not enough credits for this request. `creditsNeeded` /
`creditsAvailable` are included when the estimate is known.
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- INSUFFICIENT_CREDITS
message:
type: string
creditsNeeded:
type: number
creditsAvailable:
type: number
required:
- success
- errorCode
- message
example:
success: false
errorCode: INSUFFICIENT_CREDITS
message: Not enough credits to perform this action
creditsNeeded: 40
creditsAvailable: 12
EntitlementRequired403:
type: object
description: >-
Valid key, but the team does not have the product this endpoint belongs
to.
properties:
code:
type: string
enum:
- entitlement_required
error:
type: string
enum:
- entitlement_required
message:
type: string
product:
type: string
example: app
required:
- code
- error
- message
- product
example:
code: entitlement_required
error: entitlement_required
message: This endpoint requires the "app" product.
product: app
responses:
Unauthorized:
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
PaymentRequired:
description: >-
Payment required: a BYOK team is missing provider keys (nothing was
created or charged), a managed team has no live subscription, or there
are not enough credits.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/MissingCredentials402'
- $ref: '#/components/schemas/SubscriptionRequired402'
- $ref: '#/components/schemas/InsufficientCredits402'
examples:
missingCredentials:
value:
code: missing_credentials
message: >-
Your team uses its own provider keys (BYOK) and these are
missing or invalid: OpenRouter, ElevenLabs. Add them in
Settings → AI keys.
errorCode: MISSING_CREDENTIALS
missingProviders:
- openrouter
- elevenlabs
details: {}
subscriptionRequired:
value:
success: false
code: subscription_required
errorCode: SUBSCRIPTION_REQUIRED
message: >-
Your team generates with Hooked's keys, which are paid by your
plan. Subscribe to keep generating.
insufficientCredits:
value:
success: false
errorCode: INSUFFICIENT_CREDITS
message: Not enough credits to perform this action
creditsNeeded: 40
creditsAvailable: 12
EntitlementRequired:
description: The team does not have the product this endpoint needs
content:
application/json:
schema:
$ref: '#/components/schemas/EntitlementRequired403'
IdempotencyMismatch:
description: >-
The `Idempotency-Key` was already used with a different body. Use a new
key for a new request.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
code:
type: string
message:
type: string
details:
type: object
additionalProperties: true
required:
- success
- code
- message
example:
success: false
code: idempotency_mismatch
message: Idempotency-Key was used with a different request
details: {}
RateLimited429:
description: >-
Your team is over a rate limit: 30 POST requests per minute, 120 other
requests per minute, or 3 downloads of your URLs running at once.
Nothing ran and nothing was charged: wait `Retry-After` seconds and send
the request again. See [Rate
limits](/guides/error-handling#rate-limits-429).
headers:
Retry-After:
description: Seconds to wait before sending again.
schema:
type: integer
X-RateLimit-Limit:
description: The limit of the bucket you hit (not sent for the download cap).
schema:
type: integer
X-RateLimit-Remaining:
description: 'Requests left in this window: 0 (not sent for the download cap).'
schema:
type: integer
X-RateLimit-Reset:
description: >-
When the window ends, in Unix seconds (not sent for the download
cap).
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- RATE_LIMITED
message:
type: string
retryAfterSeconds:
type: integer
required:
- success
- errorCode
- message
- retryAfterSeconds
example:
success: false
errorCode: RATE_LIMITED
message: >-
Rate limit exceeded: 30 POST requests per minute per team. Retry
after 12 s.
retryAfterSeconds: 12
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.