Studio API

API reference for image, video, and music generation

The Studio API provides programmatic access to Girard's generation capabilities. Create images, videos, and music through simple REST API calls.

Base URL

https://www.girardai.com/api/studio

Authentication

All requests require authentication via Bearer token:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Image Generation

Generate Image

Create an image from a text prompt.

Endpoint: POST /api/studio/generate

Request Body:

Field	Type	Required	Description
`prompt`	string	Yes	Text description of the image
`negativePrompt`	string	No	What to exclude from the image
`model`	string	No	Model ID (default: "flux-pro-1.1")
`aspectRatio`	string	No	Aspect ratio (default: "1:1")
`quality`	string	No	Quality level: standard, high, ultra
`seed`	number	No	Random seed for reproducibility

Available Models:

Model ID	Description
`flux-pro-1.1`	High quality, photorealistic
`flux-dev`	Fast, good quality
`flux-pro-ultra`	Maximum quality
`recraft-v3`	Illustrations, stylized
`stable-diffusion-3.5`	General purpose
`ideogram-v2`	Text in images

Aspect Ratios:

Value	Description
`1:1`	Square
`16:9`	Widescreen
`9:16`	Portrait/Mobile
`4:3`	Standard
`3:2`	Classic photo
`21:9`	Ultra-wide

Example Request:

curl -X POST https://www.girardai.com/api/studio/generate \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene mountain landscape at golden hour, photorealistic",
    "negativePrompt": "blurry, low quality",
    "model": "flux-pro-1.1",
    "aspectRatio": "16:9",
    "quality": "high"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "gen_abc123xyz",
    "url": "https://storage.girardai.com/generations/abc123.png",
    "prompt": "A serene mountain landscape at golden hour, photorealistic",
    "model": "flux-pro-1.1",
    "aspectRatio": "16:9",
    "width": 1920,
    "height": 1080,
    "seed": 42857361,
    "creditsUsed": 2,
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

Enhance Prompt

Improve a prompt using AI.

Endpoint: POST /api/studio/enhance-prompt

Request Body:

Field	Type	Required	Description
`prompt`	string	Yes	Original prompt to enhance
`style`	string	No	Target style (photorealistic, artistic, etc.)

Example Request:

curl -X POST https://www.girardai.com/api/studio/enhance-prompt \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cat on a chair",
    "style": "photorealistic"
  }'

Response:

{
  "success": true,
  "data": {
    "original": "a cat on a chair",
    "enhanced": "A fluffy orange tabby cat sitting gracefully on an antique wooden chair, soft natural lighting streaming through a nearby window, shallow depth of field, professional pet photography, warm and cozy atmosphere, highly detailed fur texture, 8k resolution"
  }
}

Upscale Image

Increase image resolution.

Endpoint: POST /api/studio/upscale

Request Body:

Field	Type	Required	Description
`imageUrl`	string	Yes	URL of image to upscale
`scale`	number	No	Scale factor: 2 or 4 (default: 2)

Example Request:

curl -X POST https://www.girardai.com/api/studio/upscale \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://storage.girardai.com/generations/abc123.png",
    "scale": 4
  }'

Response:

{
  "success": true,
  "data": {
    "id": "upscale_xyz789",
    "url": "https://storage.girardai.com/upscaled/xyz789.png",
    "originalWidth": 512,
    "originalHeight": 512,
    "newWidth": 2048,
    "newHeight": 2048,
    "scale": 4,
    "creditsUsed": 2
  }
}

Remove Background

Remove the background from an image.

Endpoint: POST /api/studio/remove-bg

Request Body:

Field	Type	Required	Description
`imageUrl`	string	Yes	URL of image to process

Example Request:

curl -X POST https://www.girardai.com/api/studio/remove-bg \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://storage.girardai.com/generations/abc123.png"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "rmbg_def456",
    "url": "https://storage.girardai.com/processed/def456.png",
    "format": "png",
    "hasTransparency": true,
    "creditsUsed": 1
  }
}

Video Generation

Generate Video

Create a video from text or image.

Endpoint: POST /api/studio/generate-video

Request Body:

Field	Type	Required	Description
`prompt`	string	Yes	Text description of the video
`imageUrl`	string	No	Source image for image-to-video
`model`	string	No	Model ID (default: "runway-gen3")
`duration`	number	No	Duration in seconds (5-10)
`aspectRatio`	string	No	Aspect ratio (default: "16:9")

Available Models:

Model ID	Description	Max Duration
`runway-gen3`	High quality, cinematic	10s
`kling-1.5-pro`	Fast, versatile	10s
`minimax-video`	Character animation	6s
`luma-dream-machine`	Stylized, creative	5s

Example Request:

curl -X POST https://www.girardai.com/api/studio/generate-video \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A timelapse of clouds moving over a mountain peak",
    "model": "runway-gen3",
    "duration": 5,
    "aspectRatio": "16:9"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "video_abc123",
    "status": "processing",
    "estimatedTime": 120
  }
}

Check Video Status

Poll for video generation completion.

Endpoint: GET /api/studio/generate-video?id={videoId}

Response (Processing):

{
  "success": true,
  "data": {
    "id": "video_abc123",
    "status": "processing",
    "progress": 45
  }
}

Response (Completed):

{
  "success": true,
  "data": {
    "id": "video_abc123",
    "status": "completed",
    "url": "https://storage.girardai.com/videos/abc123.mp4",
    "duration": 5,
    "width": 1920,
    "height": 1080,
    "creditsUsed": 25
  }
}

Music Generation

Generate Music

Create original music from a text description.

Endpoint: POST /api/studio/generate-music

Request Body:

Field	Type	Required	Description
`prompt`	string	Yes	Description of the music
`model`	string	No	Model ID (default: "musicgen")
`duration`	number	No	Duration in seconds (10-60)
`bpm`	number	No	Beats per minute

Available Models:

Model ID	Description	Max Duration
`musicgen`	General music generation	30s
`stable-audio`	Professional quality	60s

Example Request:

curl -X POST https://www.girardai.com/api/studio/generate-music \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Upbeat electronic dance music with driving beats, 128 BPM",
    "model": "stable-audio",
    "duration": 30
  }'

Response:

{
  "success": true,
  "data": {
    "id": "music_xyz789",
    "url": "https://storage.girardai.com/music/xyz789.mp3",
    "duration": 30,
    "format": "mp3",
    "creditsUsed": 9
  }
}

Generation History

Get History

Retrieve generation history.

Endpoint: GET /api/studio/history

Query Parameters:

Parameter	Type	Description
`type`	string	Filter by type: image, video, music
`limit`	number	Max results (default: 20, max: 100)
`offset`	number	Pagination offset

Example Request:

curl -X GET "https://www.girardai.com/api/studio/history?type=image&limit=10" \
  -H "Authorization: Bearer sk_live_xxx"

Response:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "gen_abc123",
        "type": "image",
        "url": "https://storage.girardai.com/generations/abc123.png",
        "prompt": "A mountain landscape",
        "model": "flux-pro-1.1",
        "createdAt": "2025-01-15T10:30:00Z"
      }
    ],
    "total": 150,
    "limit": 10,
    "offset": 0
  }
}

Error Responses

Standard Error Format

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human readable message",
    "details": {}
  }
}

Error Codes

Code	Status	Description
`unauthorized`	401	Invalid or missing API key
`forbidden`	403	Insufficient permissions
`not_found`	404	Resource not found
`validation_error`	400	Invalid request parameters
`insufficient_credits`	402	Not enough credits
`rate_limit_exceeded`	429	Too many requests
`server_error`	500	Internal server error

Example Error

{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to complete this generation",
    "details": {
      "required": 5,
      "available": 2
    }
  }
}

Credit Usage

Operation	Credits
Image (Standard)	1
Image (High)	2
Image (Ultra)	5
Video (per second)	5
Music (per 10 seconds)	3
Upscale 2x	1
Upscale 4x	2
Background Removal	1
Prompt Enhancement	0

Previous: Authentication | Next: Chat API

Studio API

API reference for image, video, and music generation

The Studio API provides programmatic access to Girard's generation capabilities. Create images, videos, and music through simple REST API calls.

Base URL

https://www.girardai.com/api/studio

Authentication

All requests require authentication via Bearer token:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Image Generation

Generate Image

Create an image from a text prompt.

Endpoint: POST /api/studio/generate

Request Body:

Field	Type	Required	Description
`prompt`	string	Yes	Text description of the image
`negativePrompt`	string	No	What to exclude from the image
`model`	string	No	Model ID (default: "flux-pro-1.1")
`aspectRatio`	string	No	Aspect ratio (default: "1:1")
`quality`	string	No	Quality level: standard, high, ultra
`seed`	number	No	Random seed for reproducibility

Available Models:

Model ID	Description
`flux-pro-1.1`	High quality, photorealistic
`flux-dev`	Fast, good quality
`flux-pro-ultra`	Maximum quality
`recraft-v3`	Illustrations, stylized
`stable-diffusion-3.5`	General purpose
`ideogram-v2`	Text in images

Aspect Ratios:

Value	Description
`1:1`	Square
`16:9`	Widescreen
`9:16`	Portrait/Mobile
`4:3`	Standard
`3:2`	Classic photo
`21:9`	Ultra-wide

Example Request:

curl -X POST https://www.girardai.com/api/studio/generate \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene mountain landscape at golden hour, photorealistic",
    "negativePrompt": "blurry, low quality",
    "model": "flux-pro-1.1",
    "aspectRatio": "16:9",
    "quality": "high"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "gen_abc123xyz",
    "url": "https://storage.girardai.com/generations/abc123.png",
    "prompt": "A serene mountain landscape at golden hour, photorealistic",
    "model": "flux-pro-1.1",
    "aspectRatio": "16:9",
    "width": 1920,
    "height": 1080,
    "seed": 42857361,
    "creditsUsed": 2,
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

Enhance Prompt

Improve a prompt using AI.

Endpoint: POST /api/studio/enhance-prompt

Request Body:

Field	Type	Required	Description
`prompt`	string	Yes	Original prompt to enhance
`style`	string	No	Target style (photorealistic, artistic, etc.)

Example Request:

curl -X POST https://www.girardai.com/api/studio/enhance-prompt \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cat on a chair",
    "style": "photorealistic"
  }'

Response:

{
  "success": true,
  "data": {
    "original": "a cat on a chair",
    "enhanced": "A fluffy orange tabby cat sitting gracefully on an antique wooden chair, soft natural lighting streaming through a nearby window, shallow depth of field, professional pet photography, warm and cozy atmosphere, highly detailed fur texture, 8k resolution"
  }
}

Upscale Image

Increase image resolution.

Endpoint: POST /api/studio/upscale

Request Body:

Field	Type	Required	Description
`imageUrl`	string	Yes	URL of image to upscale
`scale`	number	No	Scale factor: 2 or 4 (default: 2)

Example Request:

curl -X POST https://www.girardai.com/api/studio/upscale \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://storage.girardai.com/generations/abc123.png",
    "scale": 4
  }'

Response:

{
  "success": true,
  "data": {
    "id": "upscale_xyz789",
    "url": "https://storage.girardai.com/upscaled/xyz789.png",
    "originalWidth": 512,
    "originalHeight": 512,
    "newWidth": 2048,
    "newHeight": 2048,
    "scale": 4,
    "creditsUsed": 2
  }
}

Remove Background

Remove the background from an image.

Endpoint: POST /api/studio/remove-bg

Request Body:

Field	Type	Required	Description
`imageUrl`	string	Yes	URL of image to process

Example Request:

curl -X POST https://www.girardai.com/api/studio/remove-bg \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://storage.girardai.com/generations/abc123.png"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "rmbg_def456",
    "url": "https://storage.girardai.com/processed/def456.png",
    "format": "png",
    "hasTransparency": true,
    "creditsUsed": 1
  }
}

Video Generation

Generate Video

Create a video from text or image.

Endpoint: POST /api/studio/generate-video

Request Body:

Field	Type	Required	Description
`prompt`	string	Yes	Text description of the video
`imageUrl`	string	No	Source image for image-to-video
`model`	string	No	Model ID (default: "runway-gen3")
`duration`	number	No	Duration in seconds (5-10)
`aspectRatio`	string	No	Aspect ratio (default: "16:9")

Available Models:

Model ID	Description	Max Duration
`runway-gen3`	High quality, cinematic	10s
`kling-1.5-pro`	Fast, versatile	10s
`minimax-video`	Character animation	6s
`luma-dream-machine`	Stylized, creative	5s

Example Request:

curl -X POST https://www.girardai.com/api/studio/generate-video \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A timelapse of clouds moving over a mountain peak",
    "model": "runway-gen3",
    "duration": 5,
    "aspectRatio": "16:9"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "video_abc123",
    "status": "processing",
    "estimatedTime": 120
  }
}

Check Video Status

Poll for video generation completion.

Endpoint: GET /api/studio/generate-video?id={videoId}

Response (Processing):

{
  "success": true,
  "data": {
    "id": "video_abc123",
    "status": "processing",
    "progress": 45
  }
}

Response (Completed):

{
  "success": true,
  "data": {
    "id": "video_abc123",
    "status": "completed",
    "url": "https://storage.girardai.com/videos/abc123.mp4",
    "duration": 5,
    "width": 1920,
    "height": 1080,
    "creditsUsed": 25
  }
}

Music Generation

Generate Music

Create original music from a text description.

Endpoint: POST /api/studio/generate-music

Request Body:

Field	Type	Required	Description
`prompt`	string	Yes	Description of the music
`model`	string	No	Model ID (default: "musicgen")
`duration`	number	No	Duration in seconds (10-60)
`bpm`	number	No	Beats per minute

Available Models:

Model ID	Description	Max Duration
`musicgen`	General music generation	30s
`stable-audio`	Professional quality	60s

Example Request:

curl -X POST https://www.girardai.com/api/studio/generate-music \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Upbeat electronic dance music with driving beats, 128 BPM",
    "model": "stable-audio",
    "duration": 30
  }'

Response:

{
  "success": true,
  "data": {
    "id": "music_xyz789",
    "url": "https://storage.girardai.com/music/xyz789.mp3",
    "duration": 30,
    "format": "mp3",
    "creditsUsed": 9
  }
}

Generation History

Get History

Retrieve generation history.

Endpoint: GET /api/studio/history

Query Parameters:

Parameter	Type	Description
`type`	string	Filter by type: image, video, music
`limit`	number	Max results (default: 20, max: 100)
`offset`	number	Pagination offset

Example Request:

curl -X GET "https://www.girardai.com/api/studio/history?type=image&limit=10" \
  -H "Authorization: Bearer sk_live_xxx"

Response:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "gen_abc123",
        "type": "image",
        "url": "https://storage.girardai.com/generations/abc123.png",
        "prompt": "A mountain landscape",
        "model": "flux-pro-1.1",
        "createdAt": "2025-01-15T10:30:00Z"
      }
    ],
    "total": 150,
    "limit": 10,
    "offset": 0
  }
}

Error Responses

Standard Error Format

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human readable message",
    "details": {}
  }
}

Error Codes

Code	Status	Description
`unauthorized`	401	Invalid or missing API key
`forbidden`	403	Insufficient permissions
`not_found`	404	Resource not found
`validation_error`	400	Invalid request parameters
`insufficient_credits`	402	Not enough credits
`rate_limit_exceeded`	429	Too many requests
`server_error`	500	Internal server error

Example Error

{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to complete this generation",
    "details": {
      "required": 5,
      "available": 2
    }
  }
}

Credit Usage

Operation	Credits
Image (Standard)	1
Image (High)	2
Image (Ultra)	5
Video (per second)	5
Music (per 10 seconds)	3
Upscale 2x	1
Upscale 4x	2
Background Removal	1
Prompt Enhancement	0

Previous: Authentication | Next: Chat API