> ## 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.
# Prompt to Video
> Describe a video in a prompt: Hooked writes the script, narrates it and adds the visuals
## Overview
Prompt to Video works like [Script to Video](/api-reference/video/script-to-video), except that you send a prompt instead of a script. The model writes a script for the target duration, a voice reads it and each scene gets a visual from the chosen `mediaType`:
| `mediaType` | Visuals | Settings it reads |
| - | - | - |
| `ai-images` (default) | One AI image per scene | `presetSettings`: `preset`, `aiModel`, `characterIds`, `useCharacterReferenceImage` |
| `ai-videos` | One AI video clip per scene | `presetSettings`: `preset`, `quality`, `aiModel`, `isContinuous`, `characterIds`, `characterMode`, `voiceProfile` |
| `motion-graphics` | An animated motion graphic that typesets its own copy (no captions or stickers) | `presetSettings`: `quality`, `motionStyleId`, `motionGuidelines`; `media` as optional footage |
| `media` | Your own images and videos from the media library | `media` (send at least one) |
| `gameplay` | A gameplay clip in the background (Minecraft, Subway Surfers style, etc.) | `gameplaySettings` |
Every media type also takes `aspectRatio`, `language`, `musicId`, `audio`, `content.brandingLogo`, `webhook` and `metadata`; all but `motion-graphics` take `caption` and `addStickers`. The field list on this page says which media types read each field.
**Talking characters.** With `mediaType: "ai-videos"`, one of the `talking-fruit`, `talking-objects` or `talking-organs` presets and `presetSettings.characterMode: "speaking"`, the characters say the lines themselves with the video model's own audio. There is no narrator, captions or stickers, so `audio`, `caption` and `addStickers` do not apply (`voiceId` is still required). `speaking` with any other media type or preset answers `400`.
The request returns a `projectId` right away. The video is generated and rendered in the background.
```
POST https://api.hooked.so/v1/project/create/prompt-to-video
```
***
```bash cURL theme={null}
curl -X POST "https://api.hooked.so/v1/project/create/prompt-to-video" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Three productivity habits for remote workers. Friendly tone, aimed at busy professionals.",
"voiceId": "1004",
"targetDuration": 45,
"mediaType": "ai-images",
"presetSettings": { "preset": "pixar" },
"webhook": "https://example.com/hooked/webhook?token=YOUR_SECRET"
}'
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.hooked.so/v1/project/create/prompt-to-video", {
method: "POST",
headers: {
"x-api-key": "your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
prompt: "Three productivity habits for remote workers. Friendly tone, aimed at busy professionals.",
voiceId: "1004",
targetDuration: 45,
mediaType: "ai-images",
presetSettings: { preset: "pixar" },
webhook: "https://example.com/hooked/webhook?token=YOUR_SECRET",
}),
});
const { data } = await response.json();
console.log(data.projectId);
```
```python Python theme={null}
import requests
response = requests.post(
"https://api.hooked.so/v1/project/create/prompt-to-video",
headers={"x-api-key": "your_api_key_here"},
json={
"prompt": "Three productivity habits for remote workers. Friendly tone, aimed at busy professionals.",
"voiceId": "1004",
"targetDuration": 45,
"mediaType": "ai-images",
"presetSettings": {"preset": "pixar"},
"webhook": "https://example.com/hooked/webhook?token=YOUR_SECRET",
},
)
print(response.json()["data"]["projectId"])
```
### More request bodies
```json AI video clips theme={null}
{
"prompt": "The story of the first flight across the Atlantic, told like a documentary.",
"voiceId": "1004",
"targetDuration": 60,
"mediaType": "ai-videos",
"presetSettings": { "preset": "cinematic", "quality": "pro" }
}
```
```json Talking characters theme={null}
{
"prompt": "A banana and an apple argue about which one is the healthier snack.",
"voiceId": "1004",
"targetDuration": 30,
"mediaType": "ai-videos",
"presetSettings": {
"preset": "talking-fruit",
"quality": "ultra",
"characterMode": "speaking",
"voiceProfile": "Banana: high-pitched and excited. Apple: calm and sarcastic."
}
}
```
```json Gameplay theme={null}
{
"prompt": "Five facts about octopuses that sound made up.",
"voiceId": "1004",
"mediaType": "gameplay",
"gameplaySettings": { "selectedGame": "minecraft", "selectedVideo": "minecraft-4" }
}
```
```json Your own media theme={null}
{
"prompt": "A 30-second tour of our coffee shop for Instagram.",
"voiceId": "1004",
"targetDuration": 30,
"mediaType": "media",
"media": ["cm4x9k2p10001ab12cd34ef56", "cm4x9k2p10002ab12cd34ef56", "cm4x9k2p10003ab12cd34ef56"]
}
```
***
```json 200 theme={null}
{
"success": true,
"data": {
"projectId": "cm4x9k2p10001ab12cd34ef56",
"status": "processing"
},
"message": "Prompt to Video successfully created"
}
```
```json 400 theme={null}
{
"success": false,
"message": "targetDuration: Number must be less than or equal to 120"
}
```
```json 401 theme={null}
{
"code": "not_authenticated",
"message": "Not authenticated",
"errorCode": "NOT_AUTHENTICATED",
"details": { "x-api-key": "Header not provided or API Key invalid" }
}
```
```json 402 missing keys theme={null}
{
"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": {}
}
```
```json 402 subscription theme={null}
{
"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."
}
```
```json 402 credits theme={null}
{
"success": false,
"errorCode": "INSUFFICIENT_CREDITS",
"message": "Not enough credits. Needed: 120, Available: 45",
"creditsNeeded": 120,
"creditsAvailable": 45
}
```
```json 403 theme={null}
{
"code": "entitlement_required",
"error": "entitlement_required",
"message": "This endpoint requires the \"app\" product.",
"product": "app"
}
```
***
## What happens next
1. Keep the `projectId`.
2. Either poll [`GET /v1/project/{projectId}`](/api-reference/project/details) until `video.status` is `COMPLETED` (or the project `status` is `failed`), or pass a `webhook` and wait for the call.
3. Download the file from `video.url` (or `data.url` in the webhook).
The webhook receives:
```json theme={null}
{
"status": "COMPLETED",
"message": "Video completed",
"data": {
"videoId": "cm4xa1b2c0003ab12cd34ef56",
"projectId": "cm4x9k2p10001ab12cd34ef56",
"status": "COMPLETED",
"url": "https://..."
}
}
```
A project that fails before it has a video sends `"status": "FAILED"` with `videoId: null`. See [Webhooks](/guides/webhooks) for every payload.
***
## Credits and your own keys
**Teams on Hooked's keys (managed):** the project is priced from the target duration, the media type, the quality or model and the character mode, and the credits are taken up front. With `mediaType: "media"` your library files are used as they are and cost nothing on top of the narration, however many you send (the same as a `gameplay` background). If the balance is short, the request answers `402 INSUFFICIENT_CREDITS` with `creditsNeeded` and `creditsAvailable` and nothing is created. If the project fails later, the credits are refunded automatically.
**Teams on their own keys (BYOK):** no credits are charged. The team needs these keys in **Settings → AI keys**:
* **OpenRouter**: always (script, images, video clips, captions).
* **ElevenLabs**: for the voiceover. Not needed in `speaking` mode (`ai-videos` with a talking preset), where the video model speaks.
* **Gemini**: when `presetSettings.aiModel` is `gemini_omni_flash`.
A missing key answers `402 missing_credentials` with the list in `missingProviders`, before anything is created.
***
## Errors
| Status | Body | When |
| - | - | - |
| `400` | `{ "success": false, "message": ": " }` | Validation failed. Examples: `prompt: Required` (missing) or `prompt: Prompt is required` (empty), `targetDuration: Number must be less than or equal to 120`, `voiceId: Voice "…" not found.`, `musicId: Music "…" not found.`, `media: Media "…" not found`, `media: Media is required for media type: media` (no `media`, or an empty array, with `mediaType: "media"`), `presetSettings.preset: Invalid preset "…". Allowed values are: …` (or `Custom style "custom-…" not found` for a custom style that is not your team's), `presetSettings.motionStyleId: Invalid motion style "…". Allowed values are: …`, `caption.preset: Invalid caption preset "…". Allowed values are: …`, `gameplaySettings.selectedGame: Invalid game "…". Allowed values are: …`, `presetSettings.aiModel: "…" does not generate ai-videos`, `presetSettings.characterMode: "speaking" needs mediaType ai-videos, …`, `gameplaySettings.selectedVideo: Video "…" not found in your library`, `webhook: Must be a valid HTTPS URL`, `Invalid JSON body`, or the prompt was rejected by the content filter. Settings checked by type or range report their stored path: a bad `presetSettings.quality` answers `projectSettings.preset.quality: …`, a bad `aspectRatio`, `caption` or `audio` value answers `videoSettings.aspectRatio: …`, `videoSettings.caption.…` or `videoSettings.audio.…`. |
| `401` | `not_authenticated` | Missing or invalid `x-api-key`. |
| `402` | `missing_credentials` | BYOK team without the keys listed above. |
| `402` | `subscription_required` | Managed team without an active plan. |
| `402` | `INSUFFICIENT_CREDITS` | Managed team without enough credits. |
| `403` | `entitlement_required` | The team does not have the product this endpoint needs. |
| `500` | `{ "success": false, "message": "..." }` | Unexpected error; credits taken for this request are refunded. |
Send an [`Idempotency-Key`](/guides/idempotency) header to retry safely: if a request times out or answers 5xx, sending it again with the same key and body returns the first answer instead of creating (and charging) the project twice.
***
## Writing prompts
Say what the video is about, who it is for and the tone. "Three productivity habits for remote workers, friendly tone, aimed at busy professionals" works; "a video about stuff" does not. Set `language` for the video's language, or write the prompt in it and leave `language` out.
***
## Next Steps
Follow the project until the video is ready
Payloads and delivery rules
Pick a voice
Bring your own script
## OpenAPI
````yaml POST /v1/project/create/prompt-to-video
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/project/create/prompt-to-video:
post:
tags:
- Videos
summary: Create Prompt to Video
description: >-
Writes a script from your prompt for the target duration and turns it
into a narrated video, with a visual per scene from `mediaType`. Returns
a `projectId` right away; the video is generated and rendered in the
background. BYOK: needs OpenRouter and ElevenLabs (no ElevenLabs for a
speaking cast); `aiModel: "gemini_omni_flash"` also needs Gemini.
A body that is not valid JSON answers 400 (`Invalid JSON body`). Create
endpoints are not idempotent: do not retry a POST on a timeout or 5xx
without first checking your projects, or you may create (and pay for)
the video twice.
operationId: createPromptToVideo
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
- name: dryRun
in: query
required: false
schema:
type: boolean
default: false
description: >-
`true`: only answer the price of this exact request, as `{ success:
true, data: { dryRun: true, estimatedCredits } }` with status 200.
The request is validated like a real one (a 400 or 402 says the
same), but nothing is created, queued or charged. `estimatedCredits`
is exactly what the call without `dryRun` charges a managed team; a
byok team is charged nothing. Do not send an `Idempotency-Key` with
it.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- prompt
- voiceId
properties:
prompt:
type: string
minLength: 1
maxLength: 4000
description: >-
What the video is about, who it is for and the tone (1–4,000
characters). The script is written from it.
targetDuration:
type: number
minimum: 10
maximum: 120
default: 60
description: >-
Length of the script to write, in seconds (a JSON number,
10–120). The project is priced from it.
voiceId:
type: string
minLength: 1
maxLength: 30
description: >-
The narrator: a library voice from /v1/voice/list or one of
your team's custom voices. An ID that is neither answers 400
(`voiceId: Voice "" not found.`). Still required with
`characterMode: "speaking"`, where the characters speak with
the video model's own voice and this voice is not used.
name:
type: string
maxLength: 100
description: >-
Project name (max 100 characters). Generated from the prompt
when omitted.
mediaType:
type: string
enum:
- ai-images
- ai-videos
- motion-graphics
- media
- gameplay
description: >-
Where the visuals come from:
- `ai-images`: one AI image per scene (`presetSettings`:
`preset`, `aiModel`, `characterIds`,
`useCharacterReferenceImage`).
- `ai-videos`: one AI video clip per scene
(`presetSettings`: `preset`, `quality`, `aiModel`,
`isContinuous`, `characterIds`, `characterMode`,
`voiceProfile`).
- `motion-graphics`: an animated motion graphic that
typesets its own copy (`presetSettings`: `quality`,
`motionStyleId`, `motionGuidelines`; `media` optional as
footage). No captions or stickers.
- `media`: your own images and videos from the media library
(`media` required). No `presetSettings`.
- `gameplay`: a gameplay clip in the background
(`gameplaySettings`). No `presetSettings`.
default: ai-images
presetSettings:
type: object
description: >-
Visual settings for `ai-images`, `ai-videos` and
`motion-graphics`; not used by `media` and `gameplay`. Each
field says which media types read it.
properties:
preset:
type: string
enum:
- realistic
- cinematic
- anime
- real-anime
- retro-anime
- cyberpunk-anime
- ghibli-studio
- pixar
- cartoon
- comic-book
- claymation
- fantasy
- 80s-fantasy-movie
- creative
- art-style
- sketch-black-and-white
- sketch-color
- japanese-ink
- ink-style
- haunted-linework
- neon-futuristic
- pixel-art
- collage
- lego
- technical-blueprints
- stickman
- nursery-rhyme
- south-park
- skeleton-3d
- fruit-people
- talking-fruit
- talking-objects
- talking-organs
- minecraft
- gta-v
- free-fire
- fortnite
- roblox
- pubg
- bitlife
- space-marines-40k
- bombardiro-crocodilo
- tralalero-tralala
- demon-slayer
- dragon-ball
- one-piece
- pokemon
- naruto
- attack-on-titan
- final-fantasy
- mecha-break
- alien-stage
- marvel
- dc
- star-wars
- star-trek
- harry-potter
- lord-of-the-rings
- game-of-thrones
- doctor-who
- sherlock-holmes
- stranger-things
- squid-game
- wednesday
- zelda
- genshin-impact
- dungeons-and-dragons
- rick-and-morty
- amazing-digital-circus
default: realistic
description: >-
`ai-images` / `ai-videos`: the visual style, or
`custom-` for one of your team's custom styles. Any
other value answers 400.
quality:
type: string
enum:
- base
- pro
- ultra
default: base
description: >-
`ai-videos`: picks the video model when `aiModel` is not
set. `motion-graphics`: picks the image model of its
pictures. Not used by `ai-images` (use `aiModel`).
aiModel:
type: string
enum:
- nano_banana
- nano_banana_2
- nano_banana_pro
- seedream_4_5
- seedream_5_0
- gpt_image_2
- grok_imagine_image
- seedance_1_5_pro
- seedance_2_0
- seedance_2_0_mini
- seedance_2_0_fast
- kling_3_0
- veo_3_fast
- veo_3
- veo_3_1_lite
- wan_2_7_i2v
- grok_imagine_video
- gemini_omni_flash
description: >-
`ai-images` / `ai-videos`: the model that generates the
media, instead of the default. It must match
`mediaType`, otherwise the request answers 400
(`presetSettings.aiModel: "" does not generate
`).
- `ai-images`: `nano_banana`, `nano_banana_2`,
`nano_banana_pro`, `seedream_4_5`, `seedream_5_0`,
`gpt_image_2`, `grok_imagine_image`.
- `ai-videos`: `seedance_1_5_pro`, `seedance_2_0`,
`seedance_2_0_mini`, `seedance_2_0_fast`, `kling_3_0`,
`veo_3_fast`, `veo_3`, `veo_3_1_lite`, `wan_2_7_i2v`,
`grok_imagine_video`, `gemini_omni_flash`.
BYOK: `gemini_omni_flash` needs the Gemini key.
isContinuous:
type: boolean
default: true
description: >-
`ai-videos` only: chain the clips frame to frame (each
clip starts on the last frame of the one before).
characterMode:
type: string
enum:
- narrator
- speaking
default: narrator
description: >-
`ai-videos` only. `narrator`: a voiceover over the
visuals. `speaking`: the characters say the lines
themselves with the video model's own audio (Veo 3 Fast,
unless `aiModel` is another model that makes sound).
`speaking` needs `mediaType: "ai-videos"` and the
`talking-fruit`, `talking-objects` or `talking-organs`
preset; any other `speaking` request answers 400. A
speaking cast has no narrator, captions or stickers, so
`audio`, `caption` and `addStickers` do not apply, and
BYOK teams need no ElevenLabs key.
voiceProfile:
type: string
description: >-
Only with `characterMode: "speaking"`: a short
description of how the characters sound.
characterIds:
type: array
items:
type: string
description: >-
`ai-images` / `ai-videos`: IDs of characters saved in
your team's Characters library, to keep the same people
across scenes.
useCharacterReferenceImage:
type: boolean
default: false
description: >-
`ai-images` with `characterIds` only: generate from the
saved characters' reference images.
motionStyleId:
type: string
enum:
- auto
- kinetic-typography
- minimal-2d
- modern-saas
- warm-gradient
- dark-premium
- apple-keynote
- bold-launch
- chrome-y2k
- brutalist-poster
- clay-3d
- doodle-sketch
- vox-editorial
- blueprint
- playful-education
- retro-print
default: auto
description: >-
`motion-graphics` only: the animation style. `auto` lets
the director choose. Any other value answers 400.
motionGuidelines:
type: string
maxLength: 2000
description: >-
`motion-graphics` only: free-text direction for the
animation (max 2,000 characters).
gameplaySettings:
type: object
description: '`mediaType: "gameplay"` only: the background clip.'
properties:
selectedGame:
type: string
enum:
- minecraft
- subway-s
- temple-run
- gta
- fortnite
- roblox
- free-fire
- custom
default: minecraft
description: >-
The game, or `custom` to play a video from your own
media library. Any other value answers 400.
selectedVideo:
type: string
default: minecraft-1
description: >-
The clip, as `-`: `minecraft-1`…`minecraft-9`,
`subway-s-1`…`subway-s-11`,
`temple-run-1`…`temple-run-8`, `gta-1`…`gta-12`,
`fortnite-1`…`fortnite-5`, `roblox-1`, `free-fire-1`. A
clip that does not exist plays the game's first clip.
With `selectedGame: "custom"`, the ID of a video in your
media library (400 when it is not one).
media:
type: array
maxItems: 50
items:
type: string
description: Media ID from your library
description: >-
IDs of images or videos in your team's media library (max
50). Required for `mediaType: "media"` (send at least one);
optional footage for `motion-graphics`; ignored for the
other media types. An ID that is not in your library answers
400 (`media: Media "" not found`). A media that is not
`COMPLETED` yet (an import or upload in progress) answers
`400 media: Media "" is not ready (status PROCESSING)`.
aspectRatio:
type: string
enum:
- ratio_9_16
- ratio_16_9
- ratio_1_1
default: ratio_9_16
description: Vertical, horizontal or square.
language:
type: string
description: >-
Two-letter ISO 639-1 code, e.g. `en`, `es`: the script is
written and narrated in it. Detected from the prompt when
omitted.
musicId:
type: string
maxLength: 30
description: >-
Background music: a track from /v1/music/list or your team's
own uploaded music. An ID that is neither answers 400
(`musicId: Music "" not found.`).
caption:
type: object
description: >-
Burned-in captions of the narration. Not used with
`motion-graphics` (it typesets its own copy) or a speaking
cast.
properties:
preset:
type: string
enum:
- default
- beast
- umi
- tiktok
- wrap1
- wrap2
- ariel
- hooked
- classic
- active
- bubble
- glass
- comic
- glow
- pastel
- neon
- retroTV
- red
- marker
- modern
- blue
- vivid
default: wrap1
description: Caption style. Any other value answers 400.
alignment:
type: string
enum:
- top
- middle
- bottom
default: bottom
description: Caption position.
disabled:
type: boolean
default: false
description: '`true` renders the video without captions.'
audio:
type: object
description: >-
Narrator voice settings (ElevenLabs). Any field you leave
out keeps its default. Not used by a speaking cast.
properties:
speed:
type: number
minimum: 0.7
maximum: 1.2
default: 1
description: Speaking speed.
stability:
type: number
minimum: 0
maximum: 1
default: 0.5
description: Higher is steadier, lower is more expressive.
similarityBoost:
type: number
minimum: 0
maximum: 1
default: 0.75
description: How closely the voice sticks to the original.
addStickers:
type: boolean
default: false
description: >-
Add emoji/GIF stickers anchored to the captions. Not used
with `motion-graphics` or a speaking cast.
content:
type: object
description: Branding.
properties:
brandingLogo:
type: object
description: >-
Your logo over the whole video. Drawn only with
`enabled: true` and a `url`.
properties:
enabled:
type: boolean
default: false
url:
type: string
description: >-
Public URL of the logo image (PNG with transparency
works best).
position:
type: string
enum:
- top-left
- top-right
- bottom-left
- bottom-right
default: bottom-right
size:
type: number
minimum: 20
maximum: 200
default: 100
description: Logo size (20-200).
webhook:
type: string
maxLength: 500
format: uri
description: >-
HTTPS URL on a public host, called when the video is ready
or the project fails (max 500 characters). Requests are
signed: verify the Hooked-Signature header (HMAC-SHA256 of
".") with the signing secret from Settings →
Webhooks; Hooked-Event and Hooked-Delivery headers name the
event and the delivery. No redirects are followed; 10 s
timeout; 3 immediate attempts. See the Webhooks guide for
the payload.
metadata:
type: object
additionalProperties: true
description: >-
Any JSON object of your own (max 5 KB). Stored on the
project and sent back in the webhook payload. The key
`automationId` is reserved for dashboard automations and is
removed.
example:
name: Coffee history
prompt: A 45-second history of coffee, from Ethiopia to modern cafes
targetDuration: 45
voiceId: '1'
mediaType: ai-videos
presetSettings:
quality: pro
aiModel: seedance_2_0
aspectRatio: ratio_9_16
webhook: https://yoursite.com/webhook?token=YOUR_SECRET
responses:
'200':
description: >-
Project created. Follow it with GET /v1/project/{projectId} or wait
for the webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectCreateResponse'
example:
success: true
data:
projectId: clx9p2k4m0001abcd1234efgh
status: processing
message: Prompt to Video successfully created
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/EntitlementRequired'
'409':
$ref: '#/components/responses/IdempotencyInProgress'
'422':
$ref: '#/components/responses/IdempotencyMismatch'
'429':
$ref: '#/components/responses/RateLimited429'
'500':
$ref: '#/components/responses/InternalError'
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:
ProjectCreateResponse:
type: object
properties:
success:
type: boolean
enum:
- true
data:
type: object
properties:
projectId:
type: string
description: Follow it with GET /v1/project/{projectId}
status:
type: string
enum:
- draft
- processing
- completed
- failed
description: >-
The project status right after creation, usually `draft` or
`processing`. Follow it with GET /v1/project/{projectId}.
required:
- projectId
- status
message:
type: string
required:
- success
- data
- message
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'
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
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
responses:
ValidationError:
description: Validation error (also `Invalid JSON body`)
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError400'
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'
IdempotencyInProgress:
description: >-
A request with the same `Idempotency-Key` is still running. Retry in a
few seconds.
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_conflict
message: A request with this Idempotency-Key is still in progress
details: {}
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
InternalError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
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.