Documentation

Welcome to the EMMA18 API documentation. EMMA18 provides a unified interface for accessing 300+ AI models from various providers through a single, OpenAI-compatible API.

Quick Start

Get up and running with EMMA18 in under 5 minutes.

Integration Essentials

• Base URL: https://YOUR_PLATFORM_HOST/api/v1
• Auth header: Authorization: Bearer sk-your_api_key
• Chat endpoint: POST /api/v1/chat/completions

1. Get Your API Key

Sign up for a free account and get your API key from the dashboard.

2. Install the SDK

EMMA18 works with the OpenAI SDK. Install it using pip:

3. Make Your First Request

import openai

client = openai.OpenAI(
    api_key="sk-your_api_key",
    base_url="https://YOUR_PLATFORM_HOST/api/v1"
)

response = client.chat.completions.create(
    model="deepseek/deepseek-chat",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

Common Error Hints

• 401 - Invalid or missing API key.
• 402 - Insufficient credits. Top up in Keys & Balance.
• 403 - Model exists but your account/provider token has no permission.

Authentication

EMMA18 uses API keys for authentication. Include your key in the Authorization header.

Authorization: Bearer sk-your_api_key

Available Model Names

Use these IDs in the model field. Pull the latest list before production traffic.

Chat model IDs (practical set)

deepseek/deepseek-chat
moonshotai/kimi-k2
moonshotai/kimi-k2.6
MiniMax-M2.7
GLM5.1
anthropic/claude-sonnet-4.6

Seedance task model IDs (video)

dreamina-seedance-2-0-260128
dreamina-seedance-2-0-fast-260128

Fetch the current model list via API

Discover your account-specific chat models from the models endpoint.

curl https://YOUR_PLATFORM_HOST/api/v1/models \
  -H "Authorization: Bearer sk-your_api_key"

Agent / MCP

MCP (Model Context Protocol) is a standard that lets AI agents securely call external tools and data sources with clear permissions.

When should you read MCP docs vs REST API docs?

• If your app only sends requests to chat/models endpoints, REST API docs are enough.
• If you want agents to operate tools (tickets, databases, internal systems), you need MCP-focused docs.

Minimal executable path

1. Get API key from Keys & Balance.
2. Call POST /api/v1/chat/completions with Base URL https://YOUR_PLATFORM_HOST/api/v1.
3. Add MCP integration later only when a public MCP endpoint and auth method are officially documented.

Chat Completions

Create chat-based completions using the /api/v1/chat/completions endpoint.

Request Parameters

Example Request

{
  "model": "deepseek/deepseek-chat",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the capital of France?"}
  ],
  "temperature": 0.7,
  "max_tokens": 150
}

Seedance 2.0 (Video)

Seedance 2.0 is EMMA18's async video generation API (ByteDance / Dreamina). It is not OpenAI chat/completions — create a task, then poll until a terminal status.

What you get

• Text-to-video, image-to-video, and video-to-video (t2v / i2v / v2v)
• Listed on GET /api/v1/models with capabilities.api_pattern = async_task
• USD / K-token matrix pricing (video reference × resolution) — view it in the Models hover card or the pricing section in these docs.

Authentication

Same platform API key as chat. Send it on every Seedance request:

Authorization: Bearer sk-your_api_key
Idempotency-Key: seedance-<unique-id>   # required on create

Model IDs

Use these IDs in the model field (or omit to use the gateway default):

dreamina-seedance-2-0-260128

Discover the live list with GET /api/v1/video/seedance/models or GET /api/v1/models (filter ids containing seedance).

Modes

Returns mode list, required fields, and Seedance 2.0 model list.

• t2v — text-to-video from prompt only.
• i2v — image-to-video from prompt + reference image(s).
• v2v — video-to-video from prompt + reference video(s), with optional image/audio references.

1. Create a task

Requires header Idempotency-Key. Reusing the same key with the same payload returns the original task; a different payload returns 409 idempotency_conflict.

Request parameters

t2v example (4s)

curl https://YOUR_PLATFORM_HOST/api/v1/video/seedance/tasks \
  -H "Authorization: Bearer sk-your_api_key" \
  -H "Idempotency-Key: seedance-t2v-001" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "t2v",
    "prompt": "A cinematic sunrise over calm ocean waves, soft golden light",
    "model": "dreamina-seedance-2-0-260128",
    "duration": 4,
    "resolution": "480p",
    "ratio": "9:16",
    "generate_audio": false,
    "watermark": false
  }'

Successful create returns an upstream task id:

{ "id": "cgt-xxxxxxxx" }

i2v example

curl https://YOUR_PLATFORM_HOST/api/v1/video/seedance/tasks \
  -H "Authorization: Bearer sk-your_api_key" \
  -H "Idempotency-Key: seedance-i2v-001" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "i2v",
    "prompt": "The subject turns and smiles at camera with soft lighting",
    "image_url": "https://example.com/reference-image.jpg",
    "model": "dreamina-seedance-2-0-260128",
    "duration": 4,
    "resolution": "720p",
    "ratio": "16:9"
  }'

v2v example

curl https://YOUR_PLATFORM_HOST/api/v1/video/seedance/tasks \
  -H "Authorization: Bearer sk-your_api_key" \
  -H "Idempotency-Key: seedance-v2v-001" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "v2v",
    "prompt": "Keep camera movement from the reference video, add neon cyberpunk style",
    "video_url": "https://example.com/reference-video.mp4",
    "model": "dreamina-seedance-2-0-260128",
    "duration": 4
  }'

2. Poll task status

Or POST body poll:

curl https://YOUR_PLATFORM_HOST/api/v1/video/seedance/tasks/cgt-xxxxxxxx \
  -H "Authorization: Bearer sk-your_api_key"

Status values

• running / queued — keep polling (e.g. every 5–10s)
• succeeded — video ready; read content.video_url
• failed / expired / cancelled — terminal error

Succeeded response (shape)

{
  "id": "cgt-xxxxxxxx",
  "model": "dreamina-seedance-2-0-260128",
  "status": "succeeded",
  "duration": 4,
  "resolution": "480p",
  "ratio": "9:16",
  "content": { "video_url": "https://.../video.mp4?..." },
  "usage": { "completion_tokens": 40594, "total_tokens": 40594 },
  "gateway": {
    "task_id": "cgt-xxxxxxxx",
    "billing_status": "charged",
    "billed_cost": 0.287
  }
}

Pricing & billing

Customer rates per 1K tokens (shown in your selected currency), billed on total_tokens when the task succeeds:

• Account is billed in USD credits per 1K tokens (matrix by video-reference input × resolution). The table above converts for display only.
• Live rates: GET /api/v1/video/seedance/pricing, the Models hover card, and the Playground.
• Charged once when status becomes succeeded (gateway.billing_status)

Error codes

Endpoint summary

• GET /api/v1/models — includes Seedance when enabled
• GET /api/v1/video/seedance/models
• GET /api/v1/video/seedance/modes
• GET /api/v1/video/seedance/pricing
• POST /api/v1/video/seedance/tasks
• GET /api/v1/video/seedance/tasks/{task_id}
• POST /api/v1/video/seedance/tasks/status

Models

List account-visible chat models and their capabilities.

Response

{
  "data": [
    {
      "id": "deepseek/deepseek-chat",
      "name": "DeepSeek Chat",
      "description": "General-purpose chat model",
      "context_length": 128000,
      "pricing": {
        "prompt": "0.00000015",
        "completion": "0.0000006"
      }
    }
  ]
}

Code Examples

Python

import openai

client = openai.OpenAI(
    api_key="sk-your_api_key",
    base_url="https://YOUR_PLATFORM_HOST/api/v1"
)

# Chat completion
response = client.chat.completions.create(
    model="deepseek/deepseek-chat",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

JavaScript / Node.js

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your_api_key',
  baseURL: 'https://YOUR_PLATFORM_HOST/api/v1'
});

const response = await client.chat.completions.create({
  model: 'deepseek/deepseek-chat',
  messages: [{role: 'user', content: 'Hello!'}]
});
console.log(response.choices[0].message.content);

cURL

curl https://YOUR_PLATFORM_HOST/api/v1/chat/completions \
  -H "Authorization: Bearer sk-your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-chat",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Go

client := openai.NewClient(
    openai.WithAPIKey("sk-your_api_key"),
    openai.WithBaseURL("https://YOUR_PLATFORM_HOST/api/v1"),
)

resp, err := client.Chat.Completions.New(context.Background(),
    openai.ChatCompletionNewParams{
        Model: "deepseek/deepseek-chat",
        Messages: []openai.ChatCompletionNewParamsMessages{
            {Role: openai.ChatCompletionNewParamsMessagesRoleUser, Content: "Hello!"},
        },
    },
)

Error Handling

EMMA18 uses standard HTTP status codes for errors. Error responses include a JSON body with a detail field describing the issue.