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.

Tip: EMMA18 is fully compatible with the OpenAI API. You can switch to EMMA18 by just changing the base URL and API key.

Quick Start

Get up and running with EMMA18 in under 5 minutes.

Integration Essentials

Base URL: https://emma18.com/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:

pip install openai

3. Make Your First Request

import openai

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

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

Seedance note: Seedance is a video async task API. Use POST /api/v1/video/seedance/tasks plus task polling, not /api/v1/chat/completions.

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

Warning: Keep your API key secret! Do not share it in client-side code or public repositories.

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)

doubao-seedance-2-0-260128
doubao-seedance-2-0-fast-260128

Fetch the current model list via API

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

GET /api/v1/models

curl https://emma18.com/api/v1/models \
  -H "Authorization: Bearer sk-your_api_key"

Important: Model availability can vary by account credits and upstream provider permissions. Always handle 403/429/5xx fallback.

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.

Current recommendation: If there is no officially published public MCP server yet, start with REST API first.

Minimal executable path

Get API key from Keys & Balance.
Call POST /api/v1/chat/completions with Base URL https://emma18.com/api/v1.
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.

POST /api/v1/chat/completions

Request Parameters

Parameter	Type	Required	Description
model	string	required	Model ID from `GET /api/v1/models` (e.g., deepseek/deepseek-chat)
messages	array	required	Array of message objects with role and content
temperature	number	optional	Sampling temperature (0-2)
max_tokens	integer	optional	Maximum tokens to generate
stream	boolean	optional	Enable streaming responses

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 Modes

Seedance task endpoints support explicit mode contracts for Seedance 2.0 only.

Async task pattern: Seedance is not a chat endpoint. Submit task first, then poll task status until terminal state.

Discover supported modes

GET /api/v1/video/seedance/modes

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

Mode meanings

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

Minimal request examples

t2v

curl https://emma18.com/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 drone shot over snowy mountains at sunrise",
    "model": "doubao-seedance-2-0-260128"
  }'

i2v

curl https://emma18.com/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": "doubao-seedance-2-0-260128"
  }'

v2v

curl https://emma18.com/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": "doubao-seedance-2-0-260128"
  }'

Models

List account-visible chat models and their capabilities.

GET /api/v1/models

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://emma18.com/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://emma18.com/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://emma18.com/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://emma18.com/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.

Status Code	Description
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`402`	Insufficient Credits - Add more credits to your account
`403`	Forbidden - Model/provider permission denied for this account
`404`	Not Found - Model or resource doesn't exist
`429`	Rate Limited - Too many requests
`500`	Internal Server Error - Something went wrong on our end

Note: If you encounter persistent errors, check our status page or contact support.