Videos & Quota — MagiCoal — Video API

GET

/videos

Returns a paginated list of all completed videos for the authenticated account. Only videos with a status of completed are included. Use the per_page query parameter to control page size.

Endpoint

GET   https://coals.ai/api/v1/magicoal/videos

Query Parameters

Parameter	Type	Required	Description
per_page	integer	optional	Number of results per page. Default: `15`. Maximum: `100`.
page	integer	optional	Page number to retrieve. Default: `1`.

Response — 200 OK

{
  "success": true,
  "data": [
    {
      "uuid": "3f8a2d1b-4c9e-4b7f-8d2a-1f3c5e7a9b0d",
      "type": "i2v",
      "prompt": "gentle wind blowing through the trees, slow cinematic pan",
      "status": "completed",
      "video_url": "https://coals.ai/storage/videos/3f8a2d1b-4c9e-4b7f-8d2a-1f3c5e7a9b0d.mp4",
      "thumbnail_url": "https://coals.ai/storage/thumbnails/3f8a2d1b-4c9e-4b7f-8d2a-1f3c5e7a9b0d.jpg",
      "duration_seconds": 5.0625,
      "credits_charged": 50.0,
      "created_at": "2026-03-03T14:22:11Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 42,
    "last_page": 3,
    "has_more": true
  }
}

Field	Description
uuid	Unique video identifier. Can be passed to `GET /status/{uuid}`.
type	`"i2v"` for image-to-video or `"t2v"` for text-to-video.
prompt	The prompt submitted with the generation request.
video_url	Permanent direct URL to the MP4 video file.
thumbnail_url	Permanent direct URL to a JPEG thumbnail image.
duration_seconds	Actual video duration in seconds.
meta	Pagination envelope. Use `has_more` and `last_page` to iterate pages.

curl -G https://coals.ai/api/v1/magicoal/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "per_page=20" \
  --data-urlencode "page=1"

// Using Guzzle
$response = $client->get('https://coals.ai/api/v1/magicoal/videos', [
  'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
  'query' => [
    'per_page' => '20',
    'page' => '1',
  ]
]);
$data = json_decode($response->getBody(), true);

# Using requests
import requests

response = requests.get(
  "https://coals.ai/api/v1/magicoal/videos",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  params={"per_page": "20", "page": "1"}
)
data = response.json()

# Using net/http
require "net/http"
require "json"

uri = URI("https://coals.ai/api/v1/magicoal/videos")
uri.query = URI.encode_www_form({"per_page" => "20", "page" => "1"})
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

// Using fetch (Node 18+)
const response = await fetch(`https://coals.ai/api/v1/magicoal/videos?per_page=20&page=1`, {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
});
const data = await response.json();

GET

/quota

Returns your current video generation quota, usage count for the billing period, and available credit balance. Useful for checking remaining capacity before submitting large batches.

Endpoint

GET   https://coals.ai/api/v1/magicoal/quota

Response — 200 OK

{
  "success": true,
  "data": {
    "plan": "free",
    "videos_limit": 5,
    "videos_used": 3,
    "videos_remaining": 2,
    "reset_at": "2026-04-01T00:00:00Z",
    "credit_balance": 248.5,
    "unlimited": false
  }
}

Field	Description
plan	Current plan: `"free"` or the paid plan name.
videos_limit	Maximum videos per billing period. `null` when `unlimited` is `true`.
videos_used	Videos successfully generated in the current billing period.
videos_remaining	Remaining allowed videos this period. `null` when unlimited.
reset_at	ISO 8601 timestamp when the video quota counter resets.
credit_balance	Available credits remaining in your account.
unlimited	`true` on paid plans — no monthly video cap, credit-gated only.

curl https://coals.ai/api/v1/magicoal/quota \
  -H "Authorization: Bearer YOUR_API_KEY"

// Using Guzzle
$response = $client->get('https://coals.ai/api/v1/magicoal/quota', [
  'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);
$data = json_decode($response->getBody(), true);

# Using requests
import requests

response = requests.get(
  "https://coals.ai/api/v1/magicoal/quota",
  headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

# Using net/http
require "net/http"
require "json"

uri = URI("https://coals.ai/api/v1/magicoal/quota")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

// Using fetch (Node 18+)
const response = await fetch("https://coals.ai/api/v1/magicoal/quota", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
});
const data = await response.json();

Check credit_balance before submitting a batch. I2V requires 50 credits per job; T2V requires 52. Submitting a job you cannot afford will return a 402 error and no credits will be charged.