API Documentation

Generate images and videos programmatically using our REST API. Authenticate with your API key and use the current model IDs from your workspace.

Quick Start

Get started with the API in minutes

Get your API Key

Go to Workspace Settings → API tab to create an API key.

Make your first request

Use the example below to generate your first image:

curl -X POST https://app.ai-media-studio.com/api/v1/images/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A beautiful sunset over mountains",
    "model": "openai/gpt-image-2",
    "n": 1
  }'

Discover current model IDs

Use the GET endpoints below to retrieve the currently available image and video models, including their default settings.

curl -X GET https://app.ai-media-studio.com/api/v1/images/generate \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X GET https://app.ai-media-studio.com/api/v1/videos/generate \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication

All API requests require authentication. Include your API key in the request headers using one of these methods:

Bearer Token (Recommended)

Authorization: Bearer YOUR_API_KEY

X-API-Key Header

X-API-Key: YOUR_API_KEY

Security Note: Keep your API key secret. Never expose it in client-side code or public repositories. API keys are bound to workspaces, so all team members share the same credit pool.

Generate Images

POST /api/v1/images/generate

Request Parameters

Parameter	Type	Default	Description
`prompt` Required	string	-	The text description of the image you want to generate
`model`	string	openai/gpt-image-2	The AI model to use for generation
`image_urls`	string[]	-	Reference image URLs for image-to-image editing (max 10). When provided, uses /edit endpoint.
`n`	integer	1	Number of images to generate (1-8)
`size`	string	1024x1024	Image dimensions (e.g., 1024x1024, 1792x1024)
`output_format`	string	png	Output format: png, jpeg, or webp
`make_public`	boolean	false	Make the generated image publicly shareable
`style_slug`	string	-	Apply a style preset to enhance your prompt. Use the same style slugs available in the UI (e.g., anime-style, cyberpunk-style, watercolor-style)

Model-Specific Parameters

Fal.ai Models (fal-ai/nano-banana-2)

`aspect_ratio`	string	-	Aspect ratio: auto, 21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, or 9:16. Takes precedence over size.
`resolution`	string	-	Output resolution: 0.5K, 1K, 2K, or 4K
`seed`	integer	-	Seed for deterministic outputs
`safety_tolerance`	string	6	Safety tolerance level: "1" (strictest) to "6" (least strict)
`limit_generations`	boolean	true	Limit generations from each prompt round to one
`enable_web_search`	boolean	false	Allow model web search for current generation
`sync_mode`	boolean	false	Return media as data URI and skip request history output

Fal Models (fal-ai/gpt-image-1.5)

`quality`	string	auto	Image quality: auto, standard, or hd
`background`	string	auto	Background type: auto, transparent, or opaque
`style`	string	-	Image style: natural or vivid

Response

{
  "success": true,
  "images": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://cdn.ai-media-studio.com/workspaces/.../image.png",
      "status": "completed"
    }
  ],
  "credits_used": 20,
  "credits_remaining": 980
}

Public Sharing

Set make_public: true to make the generated image publicly shareable. The response will include a share_url that anyone can access without authentication.

Request:

curl -X POST https://app.ai-media-studio.com/api/v1/images/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A stunning landscape photo",
    "model": "openai/gpt-image-2",
    "make_public": true
  }'

Response with share_url:

{
  "success": true,
  "images": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://cdn.ai-media-studio.com/workspaces/.../image.png",
      "share_url": "https://app.ai-media-studio.com/shared/media/550e8400-e29b-41d4-a716-446655440000",
      "status": "completed"
    }
  ],
  "credits_used": 20,
  "credits_remaining": 980
}

Image-to-Image (Edit Mode)

Provide image_urlsto edit or transform existing images. The API will automatically use the model's edit endpoint (e.g., openai/gpt-image-2/edit).

Single Image Edit:

curl -X POST https://app.ai-media-studio.com/api/v1/images/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Add a rainbow to the sky",
    "image_urls": ["https://example.com/your-image.jpg"],
    "model": "openai/gpt-image-2",
    "size": "1024x1024"
  }'

Multiple Reference Images (max 10):

curl -X POST https://app.ai-media-studio.com/api/v1/images/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Combine these images into a beautiful collage",
    "image_urls": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg"
    ],
    "model": "openai/gpt-image-2"
  }'

Note: When using image-to-image mode, the aspect_ratiodefaults to "auto" to preserve the original image proportions. You can override this by specifying a different aspect ratio.

Style Presets

Use style_slugto apply a style preset to your prompt - the same styles available when creating images in the UI. Your prompt will be automatically enhanced with the style's configuration to achieve the desired artistic effect.

Example with Style:

curl -X POST https://app.ai-media-studio.com/api/v1/images/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A samurai warrior standing on a cliff",
    "style_slug": "anime-style",
    "size": "1024x1536",
    "quality": "high"
  }'

Response (includes style_applied):

{
  "success": true,
  "images": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://cdn.ai-media-studio.com/workspaces/.../image.png",
      "status": "completed"
    }
  ],
  "credits_used": 20,
  "credits_remaining": 980,
  "style_applied": "anime-style"
}

How to find style slugs:Go to the image creation page in the UI and browse the available styles. The style slug is typically the style name in lowercase with hyphens (e.g., "Anime Style" → anime-style). Styles work with both text-to-image and image-to-image requests.

Generate Videos

POST /api/v1/videos/generate

Request Parameters

Parameter	Type	Default	Description
`prompt` Required	string	-	The text description of the video you want to generate
`model`	string	fal-ai/veo3.1/fast	The exact video model ID to use. Call GET /api/v1/videos/generate to see what is currently available.
`duration`	integer	-	Requested duration in seconds. The API snaps to the closest supported duration for the selected model.
`aspect_ratio`	string	-	Output aspect ratio, for example 16:9 or 9:16
`audio`	boolean	false	Enable audio generation when supported by the selected model
`make_public`	boolean	false	Make the generated video publicly shareable
`image_url`	string	-	Required for image-to-video models
`image_urls`	string[]	-	Required for reference-to-video models
`first_frame_url`	string	-	Required for first-last-frame video models, or as the start image for supported reference workflows
`last_frame_url`	string	-	Required for first-last-frame video models
`extend_video_url`	string	-	Required for extend-video models
`cfg_scale`	number	-	Classifier-free guidance scale when supported
`negative_prompt`	string	-	Negative prompt when supported
`resolution`	string	-	Resolution when supported by the selected model
`enhance_prompt`	boolean	-	Enable provider prompt enhancement when supported
`auto_fix`	boolean	-	Enable provider auto-fix when supported
`seed`	integer	-	Seed for deterministic outputs when supported
`safety_tolerance`	string	-	Safety tolerance level: "1" (strictest) to "6" (least strict)

Examples

Text-to-Video:

curl -X POST https://app.ai-media-studio.com/api/v1/videos/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic drone shot flying through snowy mountains at sunrise",
    "model": "fal-ai/veo3.1/fast",
    "duration": 4,
    "aspect_ratio": "16:9"
  }'

Image-to-Video:

curl -X POST https://app.ai-media-studio.com/api/v1/videos/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Turn this still image into a slow cinematic reveal",
    "model": "fal-ai/veo3.1/fast/image-to-video",
    "duration": 6,
    "image_url": "https://example.com/keyframe.png"
  }'

Response

{
  "success": true,
  "video": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://v3.fal.media/files/.../output.mp4",
    "status": "completed",
    "model": "fal-ai/veo3.1/fast",
    "duration": 4,
    "aspect_ratio": "16:9",
    "audio": false
  },
  "credits_used": 120,
  "credits_remaining": 880
}

Model discovery: Call GET /api/v1/videos/generate to retrieve the currently available video models, their credit costs, and default settings. The same pattern works for images with GET /api/v1/images/generate.

Available Models

Current image and video model IDs from your database

Loading models...

Available Styles

Style presets you can use with the style_slug parameter

Loading styles...

Code Examples

Example requests in different languages

Basic Request

curl -X POST https://app.ai-media-studio.com/api/v1/images/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A beautiful sunset over mountains",
    "model": "openai/gpt-image-2",
    "n": 1
  }'

With Style Preset

curl -X POST https://app.ai-media-studio.com/api/v1/images/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A samurai warrior standing on a cliff",
    "style_slug": "anime-style",
    "size": "1024x1536",
    "quality": "high"
  }'

With Model Options (Fal.ai)

curl -X POST https://app.ai-media-studio.com/api/v1/images/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic cityscape at night",
    "model": "openai/gpt-image-2",
    "n": 2,
    "size": "1536x1024",
    "quality": "high",
    "output_format": "jpeg",
    "make_public": true
  }'

OpenAI Model

curl -X POST https://app.ai-media-studio.com/api/v1/images/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cute robot holding a flower",
    "model": "fal-ai/gpt-image-1.5",
    "size": "1792x1024",
    "quality": "hd",
    "background": "transparent",
    "style": "vivid"
  }'

Error Codes

HTTP status codes and their meanings

Status Code	Name	Description
200	OK	Request successful
400	Bad Request	Invalid request parameters (e.g., missing prompt)
401	Unauthorized	Invalid or missing API key
402	Payment Required	Insufficient credits in workspace
403	Forbidden	API key does not have required scope
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error during generation

Rate Limits

API keys have configurable rate limits. The default rate limit is 60 requests per minute.

Rate limits are configured per API key. You can create multiple API keys with different rate limits for different use cases.

Tip: If you need higher rate limits, contact support or upgrade your subscription plan.

curl -X POST https://app.ai-media-studio.com/api/v1/images/generate \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A beautiful sunset over mountains", "model": "openai/gpt-image-2", "n": 1 }'

Parameter

Type

Default

Description

prompt

Required

string

The text description of the image you want to generate

model

string

openai/gpt-image-2

The AI model to use for generation

image_urls

string[]

Reference image URLs for image-to-image editing (max 10). When provided, uses /edit endpoint.

n

integer

Number of images to generate (1-8)

size

string

1024x1024

Image dimensions (e.g., 1024x1024, 1792x1024)

output_format

string

png

Output format: png, jpeg, or webp

make_public

boolean

false

Make the generated image publicly shareable

style_slug

string

Apply a style preset to enhance your prompt. Use the same style slugs available in the UI (e.g., anime-style, cyberpunk-style, watercolor-style)

{ "success": true, "images": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "url": "https://cdn.ai-media-studio.com/workspaces/.../image.png", "status": "completed" } ], "credits_used": 20, "credits_remaining": 980 }

curl -X POST https://app.ai-media-studio.com/api/v1/images/generate \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A stunning landscape photo", "model": "openai/gpt-image-2", "make_public": true }'

{ "success": true, "images": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "url": "https://cdn.ai-media-studio.com/workspaces/.../image.png", "share_url": "https://app.ai-media-studio.com/shared/media/550e8400-e29b-41d4-a716-446655440000", "status": "completed" } ], "credits_used": 20, "credits_remaining": 980 }

curl -X POST https://app.ai-media-studio.com/api/v1/images/generate \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Add a rainbow to the sky", "image_urls": ["https://example.com/your-image.jpg"], "model": "openai/gpt-image-2", "size": "1024x1024" }'

curl -X POST https://app.ai-media-studio.com/api/v1/images/generate \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Combine these images into a beautiful collage", "image_urls": [ "https://example.com/image1.jpg", "https://example.com/image2.jpg" ], "model": "openai/gpt-image-2" }'

curl -X POST https://app.ai-media-studio.com/api/v1/images/generate \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A samurai warrior standing on a cliff", "style_slug": "anime-style", "size": "1024x1536", "quality": "high" }'

Parameter

Type

Default

Description

prompt

Required

string

The text description of the video you want to generate

model

string

fal-ai/veo3.1/fast

The exact video model ID to use. Call GET /api/v1/videos/generate to see what is currently available.

duration

integer

Requested duration in seconds. The API snaps to the closest supported duration for the selected model.

aspect_ratio

string

Output aspect ratio, for example 16:9 or 9:16

audio

boolean

false

Enable audio generation when supported by the selected model

make_public

boolean

false

Make the generated video publicly shareable

image_url

string

Required for image-to-video models

image_urls

string[]

Required for reference-to-video models

first_frame_url

string

Required for first-last-frame video models, or as the start image for supported reference workflows

last_frame_url

string

Required for first-last-frame video models

extend_video_url

string

Required for extend-video models

cfg_scale

number

Classifier-free guidance scale when supported

negative_prompt

string

Negative prompt when supported

resolution

string

Resolution when supported by the selected model

enhance_prompt

boolean

Enable provider prompt enhancement when supported

auto_fix

boolean

Enable provider auto-fix when supported

seed

integer

Seed for deterministic outputs when supported

safety_tolerance

string

Safety tolerance level: "1" (strictest) to "6" (least strict)

curl -X POST https://app.ai-media-studio.com/api/v1/videos/generate \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A cinematic drone shot flying through snowy mountains at sunrise", "model": "fal-ai/veo3.1/fast", "duration": 4, "aspect_ratio": "16:9" }'

curl -X POST https://app.ai-media-studio.com/api/v1/videos/generate \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Turn this still image into a slow cinematic reveal", "model": "fal-ai/veo3.1/fast/image-to-video", "duration": 6, "image_url": "https://example.com/keyframe.png" }'

{ "success": true, "video": { "id": "550e8400-e29b-41d4-a716-446655440000", "url": "https://v3.fal.media/files/.../output.mp4", "status": "completed", "model": "fal-ai/veo3.1/fast", "duration": 4, "aspect_ratio": "16:9", "audio": false }, "credits_used": 120, "credits_remaining": 880 }

curl -X POST https://app.ai-media-studio.com/api/v1/images/generate \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A samurai warrior standing on a cliff", "style_slug": "anime-style", "size": "1024x1536", "quality": "high" }'

curl -X POST https://app.ai-media-studio.com/api/v1/images/generate \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A futuristic cityscape at night", "model": "openai/gpt-image-2", "n": 2, "size": "1536x1024", "quality": "high", "output_format": "jpeg", "make_public": true }'

curl -X POST https://app.ai-media-studio.com/api/v1/images/generate \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A cute robot holding a flower", "model": "fal-ai/gpt-image-1.5", "size": "1792x1024", "quality": "hd", "background": "transparent", "style": "vivid" }'

Status Code

Name

Description

200

Request successful

400

Bad Request

Invalid request parameters (e.g., missing prompt)

401

Unauthorized

Invalid or missing API key

402

Payment Required

Insufficient credits in workspace

403

Forbidden

API key does not have required scope

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Server error during generation